Enviar mensagens

O envio do Chat usa o mesmo contrato dos outros canais: from, to, type e payload. A diferença: to é o id da conversa, não um telefone.

Endpoint

POST /v1/chat/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

Escopo: chat:messages:send. Cada envio consome 1 crédito (CHAT_MESSAGE). O path POST /v1/chat/conversations/{id}/messages continua válido: o id da conversa vai na URL e o corpo é o mesmo (type + payload), sem to.

Campos

Campo	Obrigatório	O que é
`from`	Não	Id do Chat App. Se vier, precisa ser o app da conversa
`to`	Sim neste endpoint	Id da conversa: string ou array
`type`	Sim	`text`, `image`, `audio` ou `file`
`payload.message`	Sim se `type=text`	Texto. Em mídia, vira legenda (`caption` também vale)
`payload.mediaUrl`	Sim se não for texto	URL HTTPS da mídia
`senderExternalUserId`	Sim com API Key	Quem fala: `externalUserId` de um `USER` ou `AGENT`
`clientMessageId`	Não	Idempotência: o mesmo id devolve a mesma mensagem
`replyToId`	Não	Id da mensagem citada

Com JWT do membro, não envie senderExternalUserId: o remetente é o token. A resposta usa type em maiúsculas (TEXT, IMAGE, AUDIO, FILE).

Texto

{
  "from": "clxxapp...",
  "to": ["cnv_xxxxx"],
  "type": "text",
  "payload": {
    "message": "Oi, Alice. Seu pedido saiu para entrega."
  },
  "senderExternalUserId": "agent:clxxuser...",
  "clientMessageId": "msg_text_001"
}

Resposta (200)

{
  "success": true,
  "idempotent": false,
  "data": {
    "id": "clxxmsg...",
    "conversationId": "cnv_xxxxx",
    "type": "TEXT",
    "body": "Oi, Alice. Seu pedido saiu para entrega.",
    "mediaUrl": null,
    "createdAt": "2026-09-06T03:10:00.000Z"
  }
}

Imagem

{
  "from": "clxxapp...",
  "to": ["cnv_xxxxx"],
  "type": "image",
  "payload": {
    "mediaUrl": "https://cdn.seusite.com/comprovante.png",
    "message": "Comprovante da entrega"
  },
  "senderExternalUserId": "user_alice"
}

payload.message (ou payload.caption) é a legenda. Sem payload.mediaUrl → 400.

Áudio

{
  "from": "clxxapp...",
  "to": ["cnv_xxxxx"],
  "type": "audio",
  "payload": {
    "mediaUrl": "https://cdn.seusite.com/recado.ogg"
  },
  "senderExternalUserId": "user_bob"
}

Arquivo

{
  "from": "clxxapp...",
  "to": ["cnv_xxxxx"],
  "type": "file",
  "payload": {
    "mediaUrl": "https://cdn.seusite.com/contrato.pdf",
    "message": "Contrato assinado"
  },
  "senderExternalUserId": "agent:clxxuser..."
}

Responder a uma mensagem

{
  "from": "clxxapp...",
  "to": ["cnv_xxxxx"],
  "type": "text",
  "payload": { "message": "Combinado, obrigado" },
  "senderExternalUserId": "agent:clxxuser...",
  "replyToId": "clxxmsg..."
}

replyToId também pode ir em payload.replyToId.

JWT do membro

O app autenticado com o JWT não manda API Key.

POST /v1/chat/messages
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "to": ["cnv_xxxxx"],
  "type": "text",
  "payload": { "message": "Cheguei" }
}

Várias conversas no mesmo pedido

to aceita lista. Cada id é uma conversa do mesmo workspace.

{
  "from": "clxxapp...",
  "to": ["cnv_aaaa", "cnv_bbbb"],
  "type": "text",
  "payload": { "message": "Manutenção às 22h" },
  "senderExternalUserId": "agent:clxxuser..."
}

Uma conversa → data é o objeto da mensagem. Várias → data é um array.

WebSocket (app do usuário)

O socket não usa o body PIV1. Depois do auth:

{ "type": "message.send", "conversationId": "cnv_xxxxx", "body": "Oi", "clientMessageId": "msg_ws_1" }

Mídia no socket: messageType (image | audio | file) e mediaUrl HTTPS, ou payload.type / payload.mediaUrl. O type do frame continua sendo message.send. REST (backend) → POST /v1/chat/messages. Tempo real no app → WebSocket. Tipo fora do teto do app ou do interruptor da sala → 403 CHAT_CAPABILITY_DISABLED. DIRECT com bloqueio entre os usuários → 403 CHAT_USER_BLOCKED. Detalhes: Capacidades e bloqueio. No WebSocket o message.send também aceita type (text | image | audio | file) e mediaUrl (HTTPS). recording.start só vale se a sala tiver audio ligado.

Próximos passos

Usuário e agente: quem aparece como remetente
Eventos dos webhooks
Escopos da API Key

API Chat

Chat Apps

Chat Users

Conversas

Bloqueios

Mensagens

Endpoint

Campos

Texto

Imagem

Áudio

Arquivo

Responder a uma mensagem

JWT do membro

Várias conversas no mesmo pedido

WebSocket (app do usuário)

Próximos passos

​Endpoint

​Campos

​Texto

​Imagem

​Áudio

​Arquivo

​Responder a uma mensagem

​JWT do membro

​Várias conversas no mesmo pedido

​WebSocket (app do usuário)

​Próximos passos

Endpoint

Campos

Texto

Imagem

Áudio

Arquivo

Responder a uma mensagem

JWT do membro

Várias conversas no mesmo pedido

WebSocket (app do usuário)

Próximos passos