> ## 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. # 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. ## OpenAPI ````yaml /api-reference/openapi.yaml post /messages openapi: 3.0.3 info: title: Connecta DESK API pública version: 1.0.0 description: > API pública do Connecta DESK, disponível em `/api/v1`. O acesso é feito com um token gerado no módulo de tokens. Cada token tem permissões por **módulo × método**, e toda leitura de lista é paginada. ## Autenticação ``` Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 ``` O token pertence a uma **empresa**, e não a um usuário. A empresa usada é sempre a do token, então enviar `companyId` no corpo não tem efeito. Token ausente, inválido, revogado ou expirado recebe a mesma resposta `401`. ## Ordem de verificação 1. **token** → `401` 2. **empresa ativa** → `403` 3. **API habilitada no plano** → `403 ERR_API_NOT_ENABLED` (não se aplica a on-premise) 4. **rate limit da empresa** → `429` 5. **permissão do token** → `403 ERR_API_FORBIDDEN_SCOPE` ## Ids de usuário Todo id de usuário na API é o id do usuário **nesta empresa**, o mesmo que `GET /users` devolve. Vale para o que a API responde (`user.id`, `assignedTo.id`, `userCreated.id`) e para o que ela aceita (`userId`, `userIds`, `assignedToUserId` e o `{id}` das rotas de usuário). A mesma pessoa pode trabalhar em várias empresas, com nome e perfil diferentes em cada uma, e tem um id diferente em cada empresa. Um id que não pertence a esta empresa responde `404`, com a mesma mensagem de um id inexistente. ## Paginação Todo `GET` de lista é paginado. O `meta` traz apenas `page`, `perPage` e `hasMore`, sem o total de registros. Para percorrer tudo, avance `page` enquanto `hasMore` for `true`. ## Idempotência Opcional em `POST`/`PUT`, pelo header `Idempotency-Key`. Se você repetir a chamada com a mesma chave e o mesmo corpo, recebe a resposta já gravada (com `Idempotent-Replay: true`). Com a mesma chave e um corpo diferente, a resposta é `409`. servers: - url: https://api.connectadesk.com/api/v1 description: Produção security: - apiToken: [] tags: - name: contacts description: Cadastro de contatos, campos extras e origem de marketing. - name: tickets x-displayName: Conversas description: Abertura, transferência, encerramento e qualificação de conversas. - name: messages description: Envio assíncrono e leitura de mensagens. - name: tags description: Tags e vínculo com atendimentos. - name: queues description: Filas de atendimento e seus atendentes. - name: wrapups description: Tipos de qualificação. - name: users description: Atendentes e administradores. - name: schedules description: Mensagens programadas. - name: quick-messages description: Respostas rápidas. - name: campaigns description: Disparos em massa. - name: crm description: Painéis, etapas, cards e indicadores. - name: channels description: Canais (somente leitura). - name: reports description: Relatórios e dashboards. - name: products description: Catálogo de produtos, categorias e desempenho nas vendas. - name: custom-fields description: >- Campos personalizados de contato e de card, e variáveis globais da empresa. - name: profiles description: Perfis de permissões da empresa (somente leitura). - name: webchat description: >- Webchat nativo pelo seu sistema: abrir sessão de um visitante, enviar e ler mensagens. O token precisa do escopo `webchat` (GET e POST). paths: /messages: post: tags: - messages summary: Enviar mensagem (assíncrono) description: > 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. parameters: - $ref: '#/components/parameters/idempotencyKey' requestBody: required: true content: application/json: examples: texto: summary: Texto value: channelId: 4 type: text number: '5511999999999' contactName: Marina Alves body: 'Olá, Marina! Seu pedido #88213 foi confirmado.' template: summary: Template value: channelId: 4 type: template number: '5511999999999' template: name: confirmacao_pedido parameters: - Marina - '88213' porContato: summary: Por contato (canal sem telefone) value: channelId: 11 type: text contactId: 842 body: Oi, Maria! Seu pedido saiu para entrega. dentroDeUmAtendimento: summary: Dentro de uma conversa value: channelId: 4 type: text ticketId: 9034 body: Seu pedido saiu para entrega. closeTicket: true wrapupTypeId: 12 interativa: summary: Interativa value: channelId: 4 type: interactive number: '5511999999999' interactive: 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 interativaLista: summary: 'Interativa: lista (webchat)' value: 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 interativaLink: summary: 'Interativa: botão de link' value: channelId: 11 type: interactive ticketId: 9034 interactive: type: cta_url header: type: image image: link: https://cdn.loja.com.br/pedido.png body: text: Seu pedido saiu para entrega. action: name: cta_url parameters: display_text: Rastrear pedido url: https://loja.com.br/pedidos/88213 interativaLocalizacao: summary: 'Interativa: pedido de localização' value: channelId: 11 type: interactive ticketId: 9034 interactive: type: location_request_message body: text: Envie sua localização para calcularmos o frete. action: name: send_location interativaCarrossel: summary: 'Interativa: carrossel' value: channelId: 11 type: interactive ticketId: 9034 interactive: type: carousel body: text: Ofertas da semana action: cards: - card_index: 0 type: cta_url header: type: image image: link: https://cdn.loja.com.br/tenis.png body: text: Tênis de corrida action: name: cta_url parameters: display_text: Comprar url: https://loja.com.br/tenis - card_index: 1 type: button header: type: image image: link: https://cdn.loja.com.br/camiseta.png body: text: Camiseta dry-fit action: buttons: - type: quick_reply quick_reply: id: quero-camiseta title: Quero schema: type: object required: - channelId properties: channelId: type: integer description: >- Canal por onde a conversa acontece. Veja os canais disponíveis em `GET /channels`. example: 4 type: type: string enum: - text - media - template - interactive description: > 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). | default: text number: type: string description: >- 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. example: '5511999999999' contactId: type: integer description: >- 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`. example: 842 ticketId: type: integer description: >- Envia dentro de um atendimento que já existe. Tem precedência sobre `contactId` e `number`. example: 9034 contactName: type: string description: >- Nome dado ao contato, caso ele seja criado neste envio (só com `number`). example: Marina Alves body: type: string description: >- Texto da mensagem, ou legenda quando `type: media`. Aceita variáveis do sistema (ex.: `{{name}}`). example: 'Olá, Marina! Seu pedido #88213 foi confirmado.' template: allOf: - $ref: '#/components/schemas/TemplateInput' description: > 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. interactive: type: object description: > 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. example: 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: type: integer description: Move o atendimento para esta fila depois do envio. example: 7 openTicket: type: boolean description: Reabre o atendimento, se ele estiver encerrado. closeTicket: type: boolean description: Encerra o atendimento depois do envio. wrapupTypeId: type: integer description: >- Qualificação registrada quando o atendimento é encerrado com `closeTicket`. example: 12 multipart/form-data: schema: type: object required: - channelId properties: channelId: type: integer description: >- Canal por onde a conversa acontece. Veja os canais disponíveis em `GET /channels`. example: 4 type: type: string enum: - text - media - template - interactive description: > 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). | number: type: string description: >- Destinatário em canais de telefone. Veja `number` no corpo JSON. example: '5511999999999' contactId: type: integer description: >- Destinatário por id de contato já existente. Veja `contactId` no corpo JSON. example: 842 ticketId: type: integer description: Atendimento a que a mensagem pertence. example: 9034 body: type: string example: 'Olá, Marina! Seu pedido #88213 foi confirmado.' medias: type: string format: binary description: 'Arquivo a enviar. Obrigatório quando `type: media`.' responses: '202': description: Aceito e colocado na fila de envio. content: application/json: schema: type: object properties: data: type: object properties: jobId: type: string example: '1841' status: type: string example: queued '400': $ref: '#/components/responses/BadRequest' '402': description: > A mensagem não é colocada na fila. Dois motivos: - `ERR_API_NO_WHATSAPP_CREDITS`: canal WhatsApp Business com cobrança de WhatsApp ativada e a empresa sem crédito. Recarregue os créditos para voltar a enviar por esse canal. O saldo mínimo depende do tipo: `template` exige saldo acima do preço de uma mensagem de marketing; `text`, `media` e `interactive`, acima do preço de uma mensagem de serviço. - `ERR_API_ACTIVE_CONTACTS_LIMIT_REACHED`: a empresa atingiu o limite de contatos ativos do mês e o destinatário ainda não trocou mensagem com ela neste mês. Um contato conta uma vez por mês, na primeira mensagem trocada (enviada ou recebida); contatos que já contaram continuam recebendo normalmente. A contagem zera no dia 1º. Não vale para canais `web_whatsapp`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: semCredito: summary: Sem crédito de WhatsApp value: error: code: ERR_API_NO_WHATSAPP_CREDITS message: >- a empresa está sem crédito de WhatsApp. Recarregue os créditos para voltar a enviar por este canal. limiteContatosAtivos: summary: Limite de contatos ativos do mês value: error: code: ERR_API_ACTIVE_CONTACTS_LIMIT_REACHED message: >- a empresa atingiu o limite de contatos ativos do mês e este contato ainda não conversou com ela neste mês. Contrate mais contatos ativos ou aguarde a virada do mês. '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' components: parameters: idempotencyKey: name: Idempotency-Key in: header description: >- Chave única da operação. Se você repetir a chamada com a mesma chave e o mesmo corpo, recebe a resposta já gravada. schema: type: string maxLength: 200 example: pedido-88213-confirmacao schemas: TemplateInput: type: object description: >- Forma **simples** de enviar um template. Você informa o nome e os parâmetros, e o sistema localiza o template no canal, confere se os parâmetros correspondem ao que ele exige e monta a mensagem no formato da Meta. required: - name properties: name: type: string description: >- Nome exato do template aprovado. Consulte em `GET /channels/{id}/templates`. example: confirmacao_pedido language: type: string description: >- Idioma do template. Só é necessário quando existe mais de um template com o mesmo nome em idiomas diferentes. example: pt_BR parameters: type: object properties: body: type: array description: Um item por variável `{{n}}` do corpo, na ordem. items: type: string example: - Maria - '12345' header: type: array description: >- Um item por variável do cabeçalho de texto. Cabeçalho de mídia não usa este campo. items: type: string example: - Marina - '88213' example: name: confirmacao_pedido parameters: body: - Maria - '12345' Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Código fixo do erro, para você tratar cada caso no seu sistema. example: ERR_API_FORBIDDEN_SCOPE message: type: string details: {} responses: BadRequest: description: Corpo da requisição inválido. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_VALIDATION message: O campo `number` é obrigatório. NotFound: description: >- O recurso não existe ou pertence a outra empresa. Por segurança, a resposta é a mesma nos dois casos. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_NOT_FOUND message: Registro não encontrado. Conflict: description: Conflito de `Idempotency-Key`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_IDEMPOTENCY_KEY_REUSED message: Idempotency-Key já usada com um corpo diferente. UnprocessableEntity: description: >- O corpo está bem formado, mas falta um campo obrigatório ou algum valor não é aceito. Por exemplo, `application` diferente de `contact`/`card`, `orderedIds` vazio ou `name` em branco. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_VALIDATION message: >- O parâmetro `application` é obrigatório e aceita "contact" ou "card". securitySchemes: apiToken: type: http scheme: bearer description: Token da API no formato `sk_live_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.