Conversas e Atendimento (BETA)

BETA — API avançada. Envio de mensagens, anexos e mudanças de status têm efeito imediato no atendimento. Use um tenant de teste durante a integração.

Visão geral

O módulo de Conversas permite operar o atendimento da organização pela API única Perpetuus: listar inboxes e conversas, ler e enviar mensagens, controlar status e associar o atendimento aos cards do CRM.

Todas as requisições exigem Authorization: Bearer ... e x-tenant-id. Consulte Autenticação e Convenções antes de integrar.

Conceitos

Canal: configuração de comunicação gerenciada em /chat-channels, como WhatsApp ou e-mail.
Inbox: destino operacional de mensagens de um canal. Seu id é numérico e é usado para listar e iniciar atendimentos.
Conversa: atendimento individual em uma inbox. conversationId também é numérico.
Mensagem: item do histórico da conversa. Pode ser texto, nota interna, template ou anexo.
Card vinculado: oportunidade/tarefa do CRM associada à conversa. Cards, contatos, boards e seus vínculos usam documentId (string), não IDs numéricos.
Sincronização de contato: envia um contato CRM para o módulo de Conversas, permitindo pesquisa e histórico de atendimento.

Fluxos comuns

Ler uma inbox e suas conversas

Consulte GET /chatwoot/status.
Liste as inboxes com GET /chatwoot/inboxes.
Liste conversas com GET /chatwoot/conversations-enriched?inbox_id={inboxId}.
Leia o histórico usando GET /chatwoot/conversations/{conversationId}/messages.

conversations-enriched é recomendado para interfaces de atendimento porque já inclui o card CRM, permissões e a indicação de que um card pode ser criado.

Enviar mensagem e primeiro contato WhatsApp

Envie texto em uma conversa existente via POST /chatwoot/conversations/{conversationId}/messages.

No WhatsApp, a mensagem livre é permitida apenas dentro da janela de 24 horas após a última mensagem do contato. Fora dessa janela, envie um template aprovado em template_params:

{
  "content": "Olá, João!",
  "template_params": {
    "name": "boas_vindas",
    "category": "UTILITY",
    "language": "pt_BR",
    "processed_params": {
      "body": { "nome": "João" }
    }
  }
}

Para iniciar um atendimento, use POST /chatwoot/conversations/start com inboxId numérico e contactDocumentId ou cardDocumentId. O mesmo formato de template pode ser enviado em message.template_params.

Enviar anexos

Use POST /chatwoot/conversations/{conversationId}/messages/attachments como multipart/form-data. Envie ao menos um arquivo em attachments ou attachments[]; content é opcional. São aceitos imagens, áudios, vídeos, PDF, DOC e DOCX, com limite de 50 MB por arquivo.

Atualizar status e leitura

POST .../status com open, pending, resolved ou snoozed atualiza a conversa e o card associado.
POST .../update-last-seen marca a conversa e seus cards vinculados como lidos.
POST .../mark-unread registra o indicador de não lida para acompanhamento.

Endpoints principais

Objetivo	Endpoint
Consultar disponibilidade e inboxes	`GET /chatwoot/status`, `GET /chatwoot/inboxes`
Listar atendimentos	`GET /chatwoot/conversations-enriched`
Ler histórico	`GET /chatwoot/conversations/{conversationId}/messages`
Enviar texto ou template	`POST /chatwoot/conversations/{conversationId}/messages`
Enviar anexos	`POST /chatwoot/conversations/{conversationId}/messages/attachments`
Iniciar atendimento	`POST /chatwoot/conversations/start`
Sincronizar contato CRM	`POST /chatwoot/contacts/{contactId}/sync`
Consultar ou trocar card	`GET .../card`, `POST .../switch-card`
Criar card para conversa	`POST /chatwoot/conversations/{conversationId}/create-card`

Consulte a API Reference → Conversas para parâmetros, schemas e exemplos de todos os endpoints.

Permissões e escopo

As rotas exigem as permissões de conversas, mensagens ou contatos, conforme a operação. O acesso também respeita o escopo de carteira: uma conversa só pode ser lida ou alterada quando o usuário possui acesso ao card ou ao contato associado. Sincronização e busca global de contatos podem ser restritas a administradores em organizações com esse escopo habilitado.

On this page