API: enviar mensagens

Com a API você envia mensagens pelo canal da configuração: texto, arquivos, localização e contatos. Antes, veja como autenticar e fazer a primeira chamada.

Todos os envios usam o endereço da sua API, com o token no cabeçalho Authorization: Bearer SEU_TOKEN.

Enviar texto

Envie um POST para a URL da sua API:

{
  "number": "5511999999999",
  "body": "Olá! Seu pedido saiu para entrega.",
  "externalKey": "pedido-1234"
}

• number: o telefone, só dígitos, com código do país e DDD.
• body: o texto da mensagem.
• externalKey: opcional. Um código seu para identificar este envio, como o número do pedido, para relacionar a mensagem com o seu sistema.

Enviar para um atendimento já aberto

Em vez do telefone, você pode informar o ticketId do atendimento:

{
  "ticketId": 4990,
  "body": "Olá! Conseguiu ver a proposta?"
}

Use number ou ticketId, nunca os dois na mesma chamada.

Enviar arquivo, imagem, áudio ou documento

Há duas formas de mandar o arquivo.

Por link (o arquivo precisa estar acessível pela internet):

{
  "number": "5511999999999",
  "body": "Segue o catálogo.",
  "mediaUrl": "https://seusite.com/catalogo.pdf"
}

Em base64 (você envia o próprio arquivo dentro da chamada):

{
  "number": "5511999999999",
  "body": "Segue o contrato.",
  "mediaMessage": {
    "mediaType": "application/pdf",
    "fileName": "contrato.pdf",
    "media": "CONTEUDO_DO_ARQUIVO_EM_BASE64"
  }
}

O mediaType diz o tipo do arquivo (por exemplo application/pdf ou image/png) e o fileName é o nome que o cliente vê.

Enviar localização

Envie um POST para o caminho /location:

{
  "number": "5511999999999",
  "contents": {
    "type": "location",
    "latitude": -23.55052,
    "longitude": -46.633308,
    "name": "Nossa loja",
    "address": "Rua Exemplo, 100 - Centro"
  }
}

Enviar um contato

Envie um POST para o caminho /sendcontact:

{
  "number": "5511999999999",
  "contents": {
    "type": "contact",
    "displayName": "Setor Financeiro",
    "telephone": "5511988887777"
  }
}

Outros tipos de envio

O que	Caminho
Mensagem agendada (texto, mídia, botões ou template)	/schedule
Botões, listas e carrossel no canal API Oficial	/apioficial
Botões, listas e carrossel no canal API Plus	/apiplus
Botão de Pix	/pixbutton
Cobrança com valor	/requestpayment
SMS	/sendsms

Os botões, listas e carrosséis dependem do tipo de canal. A coleção do Postman traz um exemplo pronto de cada um.

Antes de enviar para um número novo

Para saber se o número tem WhatsApp, envie um POST para /valid-whatsapp-number:

{ "number": "5511999999999" }

Cuidados

• Não dispare mensagens em massa por aqui. Para listas de contatos, use as campanhas, feitas para disparos a listas.
• Janela de 24 horas: no canal API Oficial, texto livre só pode ser enviado a quem falou com você nas últimas 24 horas. Fora dela, use um template aprovado. Veja Templates da API Oficial.
• Canal desconectado: se o canal da configuração estiver desconectado, o envio falha. Confira antes em Canais.