Os clientes veem um estado honesto de pendente ou reconexão e as mensagens aceites não são duplicadas nem descartadas.
Usar idempotency keys estáveis
Gere uma idempotency key por intenção e mantenha-a até o SDK indicar aceitação. O motor nativo guarda corpo, timestamp e chave na outbox durável da conta antes da escrita. Não gere chave nova por atraso do ACK.
O widget web possui UI de reconexão e pendente. Clientes headless móveis expõem resumeSession, refresh e flushOutbox para uma repetição explícita depois de um token novo. O código abaixo usa a forma do wrapper TypeScript (startSession(message, options) e sendMessage(text, idempotencyKey)). Dart usa as mesmas operações com sendMessage(text, idempotencyKey: key). Clientes Swift e Kotlin diretos usam os seus DTO de plataforma com a mesma regra de chave estável, como mostram as respetivas referências de plataforma.
const sessionKey = `order-${orderId}-session-${attemptId}`;
const messageKey = `order-${orderId}-question-${attemptId}`;
// Persist each key with its own user intent until the SDK acknowledges it.
await client.startSession("I need help with my order", {
idempotencyKey: sessionKey,
});
await client.sendMessage("The order number is ORD-42", messageKey);
// Call this only from an explicit "Retry the same message" control after
// connectivity and a fresh token for the same account are available.
async function retryPendingMessage() {
await client.resumeSession();
await client.flushOutbox();
}Diferenciar resultados pendentes, rejeitados e duplicados
Erros de rede ou limitação podem deixar a aceitação incerta. Mantenha a mutação original para repetição com a mesma chave. field-invalid, payload-too-large, message-rejected e idempotency-conflict exigem correção ou investigação e não devem ser repetidos com outra chave.
session-expired exige um token novo para a mesma conta. Não chame resetSession numa falha temporária, pois reset limpa sessão e mutações pendentes.
Tornar o estado offline visível
- Mostre pendente ou reconexão ligado ao estado do SDK e mantenha o composer disponível apenas quando for seguro aceitar outra intenção.
- Ofereça Retry the same message após recuperar rede e autenticação. Preserve a chave original e desative envio duplicado durante a operação.
- Ao descartar a conversa, chame resetSession e mostre o resultado. Não limpe o estado apenas porque a app foi para segundo plano.