Mensagens

Enviar mensagem (assíncrono)

Coloca a mensagem na fila de envio e responde na hora com um jobId. O envio acontece em segundo plano, porque a comunicação com o provedor pode levar alguns segundos.

O campo type define o tipo de envio.

Destinatário. Informe um destes, nesta precedência:

campo	quando usar
`ticketId`	Enviar dentro de um atendimento que já existe. Tem precedência sobre os outros dois.
`contactId`	Enviar para um contato que já existe, em qualquer canal. É obrigatório nos canais sem telefone (Instagram, Facebook/Messenger, Webchat, Telegram) — neles só dá para enviar a quem já conversou com o canal. Tem precedência sobre `number`.
`number`	Canais de telefone (WhatsApp, RCS). Se ainda não houver contato com esse número, ele é criado. Não vale em canais sem telefone.

O destinatário é conferido antes de entrar na fila:

código	quando acontece
`ERR_API_CONTACT_NOT_IDENTIFIED` (`400`)	Nenhum de `ticketId`, `contactId` ou `number` — ou só `number` num canal sem telefone.
`ERR_API_CONTACT_NOT_FOUND` (`404`)	`contactId` inexistente ou de outra empresa.
`ERR_API_CONTACT_UNREACHABLE` (`422`)	O contato não pode receber por este canal: sem conversa anterior nele (canais sem telefone; no Webchat, sem sessão do visitante neste webchat) ou sem telefone (canais de telefone).

Interativa no Webchat. O webchat desenha as mesmas interativas da API oficial do WhatsApp que não dependem de recurso da Meta: button, list, cta_url, location_request_message e carousel. Nele, o interactive é conferido antes de entrar na fila, com os limites do WhatsApp, e o problema volta na hora: 422 com o código ERR_API_INTERACTIVE_INVALID e, na message, o campo e o motivo (por exemplo interactive.action.buttons: de 1 a 3 botões). flow, product, product_list, catalog_message, address_message, voice_call e call_permission_request não existem no webchat. Nos outros canais quem confere é o provedor, durante o envio.

Use Idempotency-Key aqui. Se a chamada der timeout e você repetir sem essa chave, o contato pode receber a mesma mensagem duas vezes.

A mídia é conferida antes de entrar na fila. Com type: media, o arquivo é lido na própria chamada, e não no envio em segundo plano — assim um arquivo problemático responde 400 na hora, em vez de devolver um jobId que falharia depois sem aviso:

código	quando acontece
`ERR_API_MEDIA_EMPTY`	O arquivo enviado tem 0 bytes.
`ERR_API_MEDIA_TYPE_UNKNOWN`	Não dá para saber o tipo: o nome veio sem extensão e o `Content-Type` da parte do multipart não foi informado.
`ERR_API_MEDIA_TYPE_MISMATCH`	O conteúdo do arquivo contradiz o tipo declarado (por exemplo, um PDF enviado como imagem).

Divergência apenas de formato dentro da mesma categoria não é recusada: um PNG declarado como JPEG é enviado normalmente. O tipo usado no envio é sempre o do conteúdo do arquivo.

POST

messages

curl --request POST \
  --url https://api.connectadesk.com/api/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channelId": 4,
  "type": "text",
  "number": "5511999999999",
  "contactName": "Marina Alves",
  "body": "Olá, Marina! Seu pedido #88213 foi confirmado."
}
'

{
  "data": {
    "jobId": "1841",
    "status": "queued"
  }
}

Autorizações

Authorization

string

header

obrigatório

Token da API no formato sk_live_….

Cabeçalhos

Idempotency-Key

string

Chave única da operação. Se você repetir a chamada com a mesma chave e o mesmo corpo, recebe a resposta já gravada.

Maximum string length: 200

Corpo

channelId

integer

obrigatório

Canal por onde a conversa acontece. Veja os canais disponíveis em GET /channels.

Exemplo:

4

type

enum<string>

padrão:text

Tipo do envio. Ele define quais outros campos são obrigatórios:

valor	o que exige
`text`	`body` com o texto.
`media`	Envio em `multipart/form-data`, com o arquivo em `medias`.
`template`	`template` com nome e parâmetros. Necessário fora da janela de 24h do WhatsApp.
`interactive`	`interactive` no formato da API oficial do WhatsApp (botões, lista, link, pedido de localização, carrossel).

Opções disponíveis:

text,

media,

template,

interactive

number

string

Destinatário em canais de telefone (WhatsApp, RCS): somente dígitos, com DDI e DDD. Se ainda não houver contato com esse número, ele é criado. Não vale em canais sem telefone.

Exemplo:

"5511999999999"

contactId

integer

Destinatário por id de um contato que já existe, em qualquer canal. É obrigatório nos canais sem telefone (Instagram, Facebook/Messenger, Webchat, Telegram) — neles só dá para enviar a quem já conversou com o canal. O contato precisa ser da empresa do token. Tem precedência sobre number.

Exemplo:

842

ticketId

integer

Envia dentro de um atendimento que já existe. Tem precedência sobre contactId e number.

Exemplo:

9034

contactName

string

Nome dado ao contato, caso ele seja criado neste envio (só com number).

Exemplo:

"Marina Alves"

body

string

Texto da mensagem, ou legenda quando type: media. Aceita variáveis do sistema (ex.: {{name}}).

Exemplo:

"Olá, Marina! Seu pedido #88213 foi confirmado."

template

object

Obrigatório quando type: template. Aceita a forma simples ({ name, parameters }), que é a recomendada: a API valida o template e monta a mensagem. Também aceita o objeto já montado com components, para quem já trabalha nesse formato.

Show child attributes

Exemplo:

{
  "name": "confirmacao_pedido",
  "parameters": { "body": ["Maria", "12345"] }
}

interactive

object

Obrigatório quando type: interactive. O objeto interactive da API oficial do WhatsApp (Cloud API), o mesmo em todos os canais que têm interativa: o payload que você já manda para o WhatsApp oficial funciona no Webchat sem adaptação.

No Webchat, os tipos e os limites conferidos na chamada:

`type`	o que leva	limites
`button`	`body`, `action.buttons[]` (`type: reply`, `reply.id`, `reply.title`); `header` e `footer` opcionais	1 a 3 botões; título até 20; id até 256, sem repetir
`list`	`body`, `action.button` (texto do botão que abre a lista), `action.sections[].rows[]` (`id`, `title`, `description`); `header` de texto e `footer` opcionais	1 a 10 seções, 1 a 10 linhas no total; botão até 20; título da linha até 24; descrição até 72; título da seção até 24 (obrigatório com mais de uma seção); id até 200
`cta_url`	`body`, `action.name: cta_url`, `action.parameters.display_text` e `url` (http ou https); `header` e `footer` opcionais	texto do botão até 20
`location_request_message`	`body`, `action.name: send_location`	sem cabeçalho
`carousel`	`body`, `action.cards[]`: `header` (imagem ou vídeo), `body` e um botão de link (`action.name: cta_url`) ou botões de resposta (`action.buttons[]`, `type: quick_reply`)	1 a 10 cartões

Em todos: body.text obrigatório, até 1024 caracteres (lista: 4096); header de texto até 60; footer até 60. header de mídia (image, video, document) só por link público http(s) — o webchat não usa mídia por id da Meta.

A escolha do contato chega como no WhatsApp: uma mensagem de texto com o título da opção, respondendo (citando) a interativa.

Exemplo:

{
  "type": "button",
  "body": {
    "text": "Podemos confirmar a entrega para amanhã?"
  },
  "action": {
    "buttons": [
      {
        "type": "reply",
        "reply": { "id": "sim", "title": "Sim" }
      },
      {
        "type": "reply",
        "reply": { "id": "nao", "title": "Reagendar" }
      }
    ]
  }
}

queueId

integer

Move o atendimento para esta fila depois do envio.

Exemplo:

7

openTicket

boolean

Reabre o atendimento, se ele estiver encerrado.

closeTicket

boolean

Encerra o atendimento depois do envio.

wrapupTypeId

integer

Qualificação registrada quando o atendimento é encerrado com closeTicket.

Exemplo:

12

Resposta

Aceito e colocado na fila de envio.

data

object

Show child attributes

curl --request POST \
  --url https://api.connectadesk.com/api/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channelId": 4,
  "type": "text",
  "number": "5511999999999",
  "contactName": "Marina Alves",
  "body": "Olá, Marina! Seu pedido #88213 foi confirmado."
}
'

{
  "data": {
    "jobId": "1841",
    "status": "queued"
  }
}

Visão geral

Endpoints

Enviar mensagem (assíncrono)

Autorizações

Cabeçalhos

Corpo

Resposta