Aparência
Chaves de API: enviar mensagens a partir de outro sistema
Para administradores e quem integra sistemas10 minutos
Uma chave de API é uma senha que permite a outro sistema (n8n, um ERP, um CRM, uma planilha automatizada) enviar mensagens de WhatsApp pelo essedr. A mensagem sai pela conexão que você escolher e fica registrada na conversa do contato, com o status de entrega, como qualquer outra mensagem.
Quando usar
Use a chave de API quando outro sistema decide quando mandar a mensagem (por exemplo, "pedido saiu para entrega"). Para a conversa acontecer dentro do essedr, use fluxos. Para o essedr avisar o seu sistema de algo que aconteceu na conversa, veja Integrações com outros sistemas.
No menu, abra Administração → Chaves de API. A tela aparece para quem tem a permissão Gerenciar integrações.
As chaves
1 Nova chave. Cria uma chave.
2 A lista. Mostra o nome, o começo da chave (só para você reconhecê-la), quando foi criada, o último uso e a situação: ativa ou revogada (com a data).
3 Revogar. A lixeira vermelha desliga a chave na hora.
4 Como usar. Logo abaixo da lista, a tela traz o endereço, os cabeçalhos e exemplos prontos para copiar.
Criando uma chave
- Clique em Nova chave.
- Escreva o nome, por exemplo "n8n produção". Use uma chave por sistema: assim, se uma delas vazar, você revoga só aquela.
- Clique em Criar chave.
- A janela Chave criada mostra a chave inteira. Copie agora: por segurança, ela não aparece de novo. Guarde no cofre de senhas ou de credenciais da ferramenta que vai usá-la.
Trate a chave como uma senha
Quem tem a chave envia mensagens pela sua empresa. Não coloque em planilhas abertas, e-mails ou mensagens de chat. Se perder a chave, não há como recuperá-la: crie uma nova e revogue a antiga.
Revogando uma chave
Clique na lixeira da chave e confirme. Quem ainda usa essa chave deixa de conseguir enviar na hora. A chave revogada continua na lista, marcada com a data, para você saber o que já existiu. Uma chave revogada não volta a funcionar: crie outra.
Como o outro sistema usa a chave
O endereço base é https://app.essedr.com.br/api/v1. Em toda chamada, envie a chave em um destes cabeçalhos:
Authorization: Bearer SUA_CHAVE
X-API-Key: SUA_CHAVEChave inválida ou revogada responde 401.
Passo 1: descobrir a conexão e o modelo
Duas consultas mostram o que você pode usar:
bash
curl https://app.essedr.com.br/api/v1/conexoes -H 'Authorization: Bearer SUA_CHAVE'
curl 'https://app.essedr.com.br/api/v1/modelos?status=approved' -H 'Authorization: Bearer SUA_CHAVE'A lista de conexões traz o id e o tipo de cada uma: oficial ou não oficial. O jeito de enviar depende disso:
| Tipo da conexão | O que dá para enviar |
|---|---|
| Oficial | Um modelo aprovado pela Meta (veja Modelos de WhatsApp). Texto solto não é aceito. |
| Não oficial (QR code) | Texto direto, imagem, vídeo, áudio ou documento. A conexão precisa estar conectada. |
Os dados de cada modelo (o ID e as variáveis) também aparecem em Modelos de WhatsApp, no botão </>.
Passo 2: enviar
Conexão oficial: enviar um modelo
bash
curl -X POST https://app.essedr.com.br/api/v1/mensagens/modelo \
-H 'Authorization: Bearer SUA_CHAVE' \
-H 'Content-Type: application/json' \
-d '{
"modelo_id": 12,
"telefone": "5586999999999",
"nome": "Maria Souza",
"variaveis": ["Maria", "12345"],
"referencia": "pedido-12345"
}'Conexão não oficial: enviar um texto direto
bash
curl -X POST https://app.essedr.com.br/api/v1/mensagens/texto \
-H 'Authorization: Bearer SUA_CHAVE' \
-H 'Content-Type: application/json' \
-d '{
"conexao_id": 7,
"telefone": "5586999999999",
"texto": "Olá, Maria! Seu pedido saiu para entrega.",
"referencia": "pedido-12345"
}'Conexão não oficial: enviar imagem, vídeo, áudio ou documento
bash
curl -X POST https://app.essedr.com.br/api/v1/mensagens/midia \
-H 'Authorization: Bearer SUA_CHAVE' \
-H 'Content-Type: application/json' \
-d '{
"conexao_id": 7,
"telefone": "5586999999999",
"tipo": "imagem",
"url": "https://seu-sistema.com/arquivos/aviso.jpg",
"legenda": "Seu pedido saiu para entrega.",
"referencia": "pedido-12345"
}'Os campos
| Campo | Para que serve |
|---|---|
conexao_id | Só no texto direto e na mídia: a conexão não oficial que envia. |
modelo_id | Só no modelo: o ID do modelo no essedr. |
telefone | O número do cliente, com DDD, só números. Um contato novo é cadastrado sozinho, e o 9º dígito não importa. |
nome | O nome do contato. Só é usado se ele ainda não existir. |
variaveis | Só no modelo: a lista de valores, na ordem de {{1}}, {{2}}... do texto do modelo. A quantidade tem que bater. |
texto | Só no texto direto: a mensagem, com até 4096 caracteres. |
tipo e url | Só na mídia: imagem, video, audio ou documento, e o link https público do arquivo, com até 16 MB. O tipo é conferido pelo conteúdo do arquivo. O áudio vira nota de voz. |
legenda | Só na mídia: o texto que acompanha imagem, vídeo ou documento. O áudio não tem legenda. |
referencia | O seu identificador do envio. Repetir a mesma referência não envia de novo (vale também o cabeçalho Idempotency-Key). |
abrir_chamado | true abre um chamado no Atendimento (opcional: fila_id), e a resposta do cliente já chega com o contexto. |
Modelo com imagem, vídeo ou documento no cabeçalho
Em GET /modelos, esses modelos trazem cabecalho. O envio então exige "midia": { "url": "https://..." }, com o link público do arquivo (até 16 MB). Em documento, nome_arquivo é o nome que o cliente vê. Modelos do WhatsApp não aceitam áudio.
Passo 3: acompanhar a entrega
O envio devolve um id. Use-o para consultar o que aconteceu:
bash
curl https://app.essedr.com.br/api/v1/mensagens/ID -H 'Authorization: Bearer SUA_CHAVE'O status vai de enviado para delivered (entregue), read (lida) ou failed (falhou, com o motivo).
O que cada resposta significa
| Código | Significado |
|---|---|
| 201 | Enviado. |
200 com duplicado: true | A mesma referencia já tinha sido enviada: nada foi enviado de novo. |
| 401 | Chave inválida ou revogada. |
| 404 | Modelo, conexão ou contato não encontrado. |
| 409 | Algo impede o envio: modelo não aprovado, texto numa conexão oficial, conexão desativada ou contato que pediu para não receber. |
| 422 | Dado inválido: variáveis, texto, link ou telefone. |
| 429 | Mais de 600 envios por minuto. Espere um pouco e tente de novo. |
| 502 | O provedor do WhatsApp recusou o envio. O motivo vem na resposta. |
A documentação completa
Quem vai programar a integração encontra a descrição técnica de todas as chamadas, com os campos de cada resposta, em https://app.essedr.com.br/api/v1/docs. Lá, o botão Try it out só funciona nas consultas, para ninguém enviar uma mensagem de verdade sem querer.
Próximo passo
Para o essedr avisar o seu sistema quando o cliente responde, veja Integrações com outros sistemas.
Conferido no sistema em 26/10/2026.