Modo Z-API
Vindo da Z-API? Troque a base URL para https://api.connectdm.app/z-api e a autenticação para o cabeçalho apikey. As rotas de envio e os callbacks seguem o formato da Z-API.
Como o modo Z-API funciona
Base URL: https://api.connectdm.app/z-api. Todas as rotas levam o cabeçalho apikey com a sua chave do ConnectDM. As rotas também aceitam o formato …/instances/:instance/token/:token/…; o token e o cabeçalho Client-Token são ignorados.
Erros voltam como { error, message }. Envio precisa do escopo messages:send; webhooks, de webhooks:write. Reações chegam como ReceivedCallback com o campo reaction.
:instanceId é o nome da instância no ConnectDM. Os callbacks são assinados com x-centralizer-signature, como os demais webhooks.
POSTTexto (Z-API)
Envia texto no formato Z-API.
phonestringObrigatório- Número com DDI e DDD, só dígitos, ou o grupo (<id>-group ou JID).
messagestringObrigatório- Texto.
delayMessagenumberOpcional- Segundos de espera antes de enviar (0 a 15).
delayTypingnumberOpcional- Segundos mostrando "digitando…" antes de enviar (0 a 15). Vale o maior dos dois.
messageIdstringOpcional- ID da mensagem a responder (citação).
curl -X POST https://api.connectdm.app/z-api/instances/loja/send-text \
-H "apikey: sk_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"phone": "5511999998888",
"message": "Olá do ConnectDM 👋",
"delayTyping": 2
}'POSTImagem (Z-API)
Envia imagem a partir de URL pública ou base64.
phonestringObrigatório- Número com DDI e DDD, só dígitos, ou o grupo (<id>-group ou JID).
imagestringObrigatório- URL pública ou base64.
captionstringOpcional- Legenda.
delayMessagenumberOpcional- Segundos de espera antes de enviar (0 a 15).
delayTypingnumberOpcional- Segundos mostrando "digitando…" antes de enviar (0 a 15). Vale o maior dos dois.
curl -X POST https://api.connectdm.app/z-api/instances/loja/send-image \
-H "apikey: sk_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"phone": "5511999998888",
"image": "https://exemplo.com/produto.png",
"caption": "Confira!"
}'POSTÁudio (Z-API)
Envia áudio como mensagem de voz.
phonestringObrigatório- Número com DDI e DDD, só dígitos, ou o grupo (<id>-group ou JID).
audiostringObrigatório- URL pública ou base64.
delayMessagenumberOpcional- Segundos de espera antes de enviar (0 a 15).
delayTypingnumberOpcional- Segundos mostrando "digitando…" antes de enviar (0 a 15). Vale o maior dos dois.
curl -X POST https://api.connectdm.app/z-api/instances/loja/send-audio \
-H "apikey: sk_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"phone": "5511999998888",
"audio": "https://exemplo.com/recado.ogg"
}'POSTDocumento (Z-API)
Envia documento; a extensão vai no caminho (pdf, docx, xlsx…).
phonestringObrigatório- Número com DDI e DDD, só dígitos, ou o grupo (<id>-group ou JID).
documentstringObrigatório- URL pública ou base64.
fileNamestringOpcional- Nome exibido; a extensão é adicionada se faltar.
delayMessagenumberOpcional- Segundos de espera antes de enviar (0 a 15).
delayTypingnumberOpcional- Segundos mostrando "digitando…" antes de enviar (0 a 15). Vale o maior dos dois.
curl -X POST https://api.connectdm.app/z-api/instances/loja/send-document/:extension \
-H "apikey: sk_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"phone": "5511999998888",
"document": "https://exemplo.com/boleto.pdf",
"fileName": "boleto"
}'PUTTodos os callbacks de uma vez
Usa a mesma URL para os quatro callbacks. Valor vazio remove.
valuestringObrigatório- URL https do seu servidor.
curl -X PUT https://api.connectdm.app/z-api/instances/loja/token/:token/update-every-webhooks \
-H "apikey: sk_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"value": "https://seu-app.com/zapi"
}'PUTCallback por evento
Uma URL por callback: troque o final por update-webhook-received, update-webhook-delivery, update-webhook-message-status ou update-webhook-connected.
valuestringObrigatório- URL https, ou vazio para remover.
curl -X PUT https://api.connectdm.app/z-api/instances/loja/token/:token/update-webhook-received \
-H "apikey: sk_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"value": "https://seu-app.com/zapi/received"
}'Formato dos callbacks
Todo callback é um POST JSON com o campo type. momment é o horário em milissegundos (grafia da Z-API).
| type | Quando | Campos principais |
|---|---|---|
ReceivedCallback | Mensagem recebida | instanceId, messageId, phone, chatName, senderName, fromMe, isGroup, participantPhone, status "RECEIVED", momment e o conteúdo (text, image, audio, video, document, sticker, location, contact, reaction, listResponseMessage, buttonsResponseMessage) |
DeliveryCallback | Mensagem enviada pela instância | phone, zaapId, messageId, instanceId, momment |
MessageStatusCallback | Mudança de status | instanceId, status "SENT" | "RECEIVED" | "READ" | "PLAYED", ids[], phone, isGroup, momment |
ConnectedCallback | Instância conectou | instanceId, connected: true, momment |
DisconnectedCallback | Instância caiu (vai para a URL de connected) | instanceId, momment, error |
{
"type": "ReceivedCallback",
"instanceId": "loja",
"messageId": "3EB0A1B2C3D4",
"phone": "5511999998888",
"fromMe": false,
"isGroup": false,
"senderName": "Maria",
"status": "RECEIVED",
"momment": 1763300000000,
"text": { "message": "Oi, meu pedido chegou?" }
}