Atendimento humano (trava do bot)

Toda operação chega nesse momento: um atendente humano precisa assumir a conversa. Sem uma trava, o robô continua respondendo por cima da pessoa — dois “atendentes” na mesma conversa, falando coisas diferentes.

A plataforma resolve isso com uma regra simples:

O bot para de responder, mas a plataforma continua ouvindo tudo.

Assim, quando o bot voltar, ele já sabe o que o atendente combinou com o cliente.

Dois níveis de trava

O que acontece durante a pausa

Com a conversa pausada, quando o cliente manda mensagem:

• ✅ a mensagem é gravada no histórico;
• ✅ o evento conversation.inbound é enviado para os seus webhooks;
• ❌ não há resposta do robô;
• ❌ não aparece o “digitando…”;
• ❌ nada é enviado ao cliente.

Quando o próprio agent entrega

Além da pausa pela API, o agent pode entregar a conversa a uma pessoa por conta própria — para as situações que você escreveu no perfil dele (“o cliente pede um humano”, “pedido de cancelamento”, “reclamação”). Isso só acontece com a capacidade Entregar a um humano ligada na tela do agent; ela nasce desligada.

Quando ele entrega, tudo isto acontece no mesmo instante:

1. O cliente recebe uma última mensagem escrita pelo agent, e nada mais depois dela.
2. No número não oficial (uazapi), a conversa recebe a etiqueta correspondente à situação — pelo nome exato que você escreveu no perfil.
3. Você e a equipe recebem um aviso pelo canal do dono, com o telefone do cliente, a etiqueta e o motivo.
4. O bot fica pausado nessa conversa — o mesmo estado da pausa pela API.

A retomada continua sendo pela API

Entregar é automático; retomar não é. Depois da entrega, a conversa só volta ao robô com POST .../conversations/resume — o mesmo endereço da tabela abaixo.

Receita pronta (número não oficial). Se você usa n8n ou parecido, dá para religar o bot tirando a etiqueta no aplicativo:

1. No uazapi, assine o webhook de chat_labels apontando para o seu n8n.
2. No n8n, filtre o evento em que a etiqueta de atendimento foi removida do chat.
3. Chame POST /orgs/{orgId}/agents/{agentId}/conversations/resume com o conversationId daquele chat.

Para espelhar a entrega no seu CRM ou numa planilha, assine o evento conversation.handoff — veja Webhooks de saída.

Como o bot retoma com contexto

Ao retomar:

1. O que ficou acumulado durante a pausa não gera resposta retroativa — o robô não vomita cinco respostas atrasadas de uma vez.
2. O robô responde apenas a próxima mensagem nova.
3. Tudo que aconteceu durante a pausa continua no histórico e vai junto no próximo pedido ao agent.

A fala do atendente também entra no histórico

Nos dois canais, o que o atendente digita no aparelho/aplicativo do número é capturado e gravado com o papel de operador. No histórico enviado ao agent, esse trecho aparece prefixado por [atendente humano]: , para que ele entenda que aquilo não foi dito pelo robô.

• No canal não oficial (uazapi), a captura vem do próprio evento de mensagem.
• No canal oficial (Datafy), a captura depende da assinatura smb_message_echoes no painel Meta/Datafy — veja Conectar WhatsApp oficial. Sem ela, a fala do atendente não chega à plataforma.

Os endereços da API

Todos usam a mesma autenticação das demais chamadas da organização.

Exemplos

Pausar uma conversa (o atendente assumiu):

curl -X POST "$GATEWAY_URL/orgs/<ID_DA_ORG>/agents/<ID_DO_AGENT>/conversations/pause" \
  -H "Authorization: Bearer <SUA_CHAVE_DO_GATEWAY>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "<ID_DA_CONVERSA>",
    "provider": "uazapi"
  }'

Retomar:

curl -X POST "$GATEWAY_URL/orgs/<ID_DA_ORG>/agents/<ID_DO_AGENT>/conversations/resume" \
  -H "Authorization: Bearer <SUA_CHAVE_DO_GATEWAY>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "<ID_DA_CONVERSA>",
    "provider": "uazapi"
  }'

Consultar se está pausada:

curl "$GATEWAY_URL/orgs/<ID_DA_ORG>/agents/<ID_DO_AGENT>/conversations/state?conversationId=<ID_DA_CONVERSA>&provider=uazapi" \
  -H "Authorization: Bearer <SUA_CHAVE_DO_GATEWAY>"

Desligar o robô do agent inteiro:

curl -X POST "$GATEWAY_URL/orgs/<ID_DA_ORG>/agents/<ID_DO_AGENT>/bot/pause" \
  -H "Authorization: Bearer <SUA_CHAVE_DO_GATEWAY>"

Os dois campos que confundem

• conversationId é a mesma chave que a plataforma usa internamente para a conversa — o identificador do cliente no canal (o telefone/chatid). É o mesmo valor que chega no conversation_id dos seus webhooks.
• provider é obrigatório e vale datafy ou uazapi. O mesmo telefone pode falar pelos dois canais, e cada um é uma conversa diferente. Errar o provider pausa a conversa errada.

Detalhes que valem saber

• A pausa não expira sozinha. Quem pausou precisa retomar.
• Não existe pausa automática por adivinhação (“detectei um humano, pauso sozinho”) — a trava é sempre explícita, decidida pelo seu sistema.
• As chamadas autenticadas de envio de mensagem não são afetadas pela trava: se o seu sistema mandar uma mensagem de propósito, ela sai. A trava vale para o robô reagindo sozinho.

Problemas comuns