> ## Documentation Index > Fetch the complete documentation index at: https://docs.connectadesk.com/llms.txt > Use this file to discover all available pages before exploring further. # Webchat > Como usar o webchat do Connecta DESK pela API: enviar mensagens para visitantes, incluindo mensagens interativas, e conversar como visitante a partir do seu próprio sistema. 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: A empresa envia mensagens para quem está no webchat, com `POST /messages`, inclusive mensagens interativas. Módulo `messages`. 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: ```bash theme={null} 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](/guides/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. ```json theme={null} { "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`: ```json theme={null} { "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. Use o `slug` do webchat (de `GET /webchat`). Com `externalId`, a mesma pessoa volta sempre para a mesma sessão e o mesmo contato. ```bash theme={null} 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. ```bash theme={null} 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`. Sem tempo real, consulte com `after` igual ao `createdAt` da última mensagem recebida: ```bash theme={null} 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: ```json theme={null} { "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: ```json theme={null} { "location": { "latitude": -23.561399, "longitude": -46.656571 }, "quotedMessageId": "6f1d2c1e-8a8b-4f35-a1e6-1f2f3c4d5e6f" } ``` Qualquer mensagem pode responder outra com `quotedMessageId`. Os quatro tipos de envio, o `jobId` e os estados do job. Os códigos do webchat e das mensagens. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.