Webchat

O webchat é um canal como os outros: cada webchat da empresa tem um channelId (veja GET /webchat ou GET /channels) e as conversas dele entram na caixa de entrada. Pela API você faz duas coisas com ele:

Falar com o visitante

A empresa envia mensagens para quem está no webchat, com POST /messages, inclusive mensagens interativas. Módulo messages.

Ser o visitante

O seu sistema abre a sessão de um usuário seu, envia as mensagens dele e lê as respostas da equipe. Módulo webchat.

Enviar para um visitante

O visitante do webchat não tem telefone obrigatório, então o destinatário é o ticketId de uma conversa ou o contactId de quem já abriu este webchat:

curl --request POST \
  --url "$CONNECTA_URL/messages" \
  --header "Authorization: Bearer $CONNECTA_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: pedido-88213-aviso" \
  --data '{
    "channelId": 11,
    "type": "text",
    "contactId": 842,
    "body": "Oi, Maria! Seu pedido saiu para entrega."
  }'

Contato que nunca abriu este webchat responde 422 ERR_API_CONTACT_UNREACHABLE. O resto do envio é igual aos outros canais: 202 com jobId, e a consulta do job em GET /messages/jobs/{jobId}. Veja Enviar mensagens.

O webchat não usa template. type: template só vale nos canais de WhatsApp oficial.

Mensagens interativas

O webchat mostra ao visitante as mesmas mensagens interativas da API oficial do WhatsApp, com o mesmo objeto interactive: o payload que você já manda para o WhatsApp oficial vale no webchat sem nenhuma adaptação. Só muda o channelId e o destinatário.

`type`	O que o visitante vê
`button`	Até 3 botões de resposta, com cabeçalho (texto, imagem, vídeo ou documento) e rodapé opcionais.
`list`	Um botão que abre a lista de opções, organizadas em seções, com descrição.
`cta_url`	Um botão que abre o link numa nova aba.
`location_request_message`	Um botão que pede a localização ao navegador e a envia.
`carousel`	Cartões lado a lado, cada um com imagem ou vídeo, texto e um botão de link ou botões de resposta.

flow, product, product_list, catalog_message, address_message, voice_call e call_permission_request dependem de recursos da Meta e não existem no webchat.

{
  "channelId": 11,
  "type": "interactive",
  "contactId": 842,
  "interactive": {
    "type": "list",
    "header": { "type": "text", "text": "Cardápio" },
    "body": { "text": "O que você vai pedir?" },
    "footer": { "text": "Entrega em até 40 min" },
    "action": {
      "button": "Ver cardápio",
      "sections": [
        {
          "title": "Lanches",
          "rows": [
            { "id": "x-burger", "title": "X-Burger", "description": "Pão, carne e queijo" },
            { "id": "x-salada", "title": "X-Salada" }
          ]
        },
        { "title": "Bebidas", "rows": [{ "id": "suco", "title": "Suco natural" }] }
      ]
    }
  }
}

No webchat, o interactive é conferido na própria chamada, com os limites do WhatsApp (3 botões, 10 linhas, títulos de 20 ou 24 caracteres e os demais, listados no campo interactive de POST /messages). Fora deles, a resposta é 422 na hora, com o campo e o motivo na message:

{
  "error": {
    "code": "ERR_API_INTERACTIVE_INVALID",
    "message": "interactive.action.buttons: de 1 a 3 botões"
  }
}

Mídia do cabeçalho e dos cartões só por link público http ou https. O webchat não usa mídia enviada para a Meta (id).

A resposta do visitante

A escolha chega como no WhatsApp: uma mensagem de texto do visitante com o título da opção, respondendo (citando) a mensagem interativa. A localização chega como a do WhatsApp, com mediaType: locationMessage. Se você acompanha a conversa por GET /tickets/{ticketId}/messages, nada muda em relação ao WhatsApp.

Conversar como visitante

Com o módulo webchat, o seu sistema faz o papel do visitante: por exemplo, um app próprio que mostra o atendimento dentro dele.

Abra a sessão

Use o slug do webchat (de GET /webchat). Com externalId, a mesma pessoa volta sempre para a mesma sessão e o mesmo contato.

curl --request POST \
  --url "$CONNECTA_URL/webchat/site-institucional-3f9a/sessions" \
  --header "Authorization: Bearer $CONNECTA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "externalId": "usuario-1029",
    "visitor": { "name": "Maria Souza", "email": "maria@email.com" }
  }'

Guarde o session.id. A resposta também traz um visitorToken, que o seu front usa para receber as mensagens em tempo real (/webchat, Socket.IO, auth: { token }) sem expor o token da API.

Envie as mensagens do visitante

curl --request POST \
  --url "$CONNECTA_URL/webchat/site-institucional-3f9a/sessions/$SESSAO/messages" \
  --header "Authorization: Bearer $CONNECTA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "text": "Olá, gostaria de um orçamento" }'

O primeiro envio abre o atendimento na fila do webchat. Arquivo vai em multipart/form-data, no campo media.

Leia as respostas

Sem tempo real, consulte com after igual ao createdAt da última mensagem recebida:

curl --request GET \
  --url "$CONNECTA_URL/webchat/site-institucional-3f9a/sessions/$SESSAO/messages?after=2026-10-01T13:45:00.000Z" \
  --header "Authorization: Bearer $CONNECTA_TOKEN"

Marque como lidas com POST /webchat/{slug}/sessions/{sessionId}/read e encerre com POST /webchat/{slug}/sessions/{sessionId}/close.

Responder a uma mensagem interativa

Nas mensagens interativas da empresa, interactive traz o que desenhar (tipo, cabeçalho, corpo, rodapé e as opções) e options lista as opções de resposta com id e title. Para escolher uma, envie o id da mensagem e o id da opção:

{ "interactiveReply": { "messageId": "6f1d2c1e-8a8b-4f35-a1e6-1f2f3c4d5e6f", "optionId": "x-burger" } }

O título gravado vem da própria mensagem: não é preciso, nem possível, mandar outro. Opção que não está na mensagem responde 422 ERR_WEBCHAT_INTERACTIVE_REPLY_INVALID. Para um pedido de localização (interactive.type: location_request), envie as coordenadas, citando o pedido:

{
  "location": { "latitude": -23.561399, "longitude": -46.656571 },
  "quotedMessageId": "6f1d2c1e-8a8b-4f35-a1e6-1f2f3c4d5e6f"
}

Qualquer mensagem pode responder outra com quotedMessageId.

Enviar mensagens

Os quatro tipos de envio, o jobId e os estados do job.

Erros

Os códigos do webchat e das mensagens.

Comece aqui

Fundamentos

Guias

Falar com o visitante

Ser o visitante

Enviar para um visitante

Mensagens interativas

A resposta do visitante

Conversar como visitante

Responder a uma mensagem interativa

Enviar mensagens

Erros

Falar com o visitante

Ser o visitante

​Enviar para um visitante

​Mensagens interativas

​A resposta do visitante

​Conversar como visitante

​Responder a uma mensagem interativa

Enviar mensagens

Erros

Enviar para um visitante

Mensagens interativas

A resposta do visitante

Conversar como visitante

Responder a uma mensagem interativa