Uma integração, seis passos
A Tenvio separa o acesso ao painel da API programática. Você cria e protege credenciais no painel; sua aplicação usa apenas a chave, o identificador da instância e o segredo do webhook.
- 1Crie a credencialEscolha o perfil CRM no painel.
- 2Descubra a instânciaConfirme que está pronta.
- 3Cadastre o webhookGuarde o segredo uma vez.
- 4Receba o eventoValide e persista antes do 2xx.
- 5Envie a respostaUse idempotência em todo envio.
- 6Concilie o estadoConsulte ou processe os eventos.
Prepare seu ambiente
Os exemplos usam Node.js 24 ou superior e somente recursos nativos. Nunca coloque a chave no código-fonte, em URLs ou em logs.
TENVIO_API_KEY=tvk_PREFIXO.SEGREDO_EXIBIDO_UMA_VEZ
TENVIO_INSTANCE_ID=00000000-0000-4000-8000-000000000000
TENVIO_API_URL=https://api.tenvioapi.com.brA chave da API e o segredo do webhook aparecem somente na criação. Guarde-os em um cofre ou arquivo restrito. A Tenvio não consegue mostrá-los novamente.
Obtenha sua credencial
- Entre no painel da Tenvio e abra Integrações.
- Em Credenciais, selecione Criar credencial.
- Use Selecionar perfil CRM para marcar os cinco escopos abaixo.
- Copie a chave exibida e guarde-a fora do código.
instances:readmessages:readmessages:writewebhooks:managewebhooks:replayPara integrações menores, remova escopos que não serão usados. Uma credencial sem o escopo exigido recebe HTTP 403.
Identifique a instância
Use a API para listar suas instâncias. Compare o campo name com o nome exibido no painel, guarde o id correspondente e confirme readyForMessages antes de enviar.
curl https://api.tenvioapi.com.br/v1/instances -H "Authorization: Bearer $TENVIO_API_KEY" -H "Accept: application/json"{
"data": [{
"id": "00000000-0000-4000-8000-000000000000",
"name": "Atendimento",
"sessionStatus": "authenticated",
"deviceStatus": "online",
"readyForMessages": true
}]
}Configure um webhook
Seu endpoint precisa usar HTTPS público, responder rapidamente e aceitar POST. Cadastre-o pelo painel ou pela API. O segredo retornado assina cada entrega.
curl https://api.tenvioapi.com.br/v1/webhooks -X POST -H "Authorization: Bearer $TENVIO_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: webhook-crm-0001" -d '{
"name": "CRM de atendimento",
"url": "https://crm.example.com/webhooks/tenvio",
"eventFilters": [
"message.received",
"message.submitted",
"message.delivered",
"message.read",
"message.failed"
]
}'Valide a assinatura sobre o corpo bruto, recuse timestamps com diferença superior a cinco minutos e persista o evento. Entregas podem se repetir; deduplique pelo ID do evento.
Receba uma mensagem
Quando uma mensagem chega ao WhatsApp conectado, a Tenvio envia message.received. O campo messageId permite citar a mensagem; sua aplicação deve guardar o destino de resposta recebido pelo conector.
import { createHmac, timingSafeEqual } from 'node:crypto'
function assinaturaValida({ segredo, timestamp, corpoBruto, assinatura }) {
const esperado = createHmac('sha256', segredo)
.update(timestamp + '.' + corpoBruto)
.digest('hex')
const recebido = assinatura.replace(/^v1=/, '')
const a = Buffer.from(esperado, 'hex')
const b = Buffer.from(recebido, 'hex')
return a.length === b.length && timingSafeEqual(a, b)
}X-Tenvio-Delivery-IdX-Tenvio-Event-IdX-Tenvio-Event-VersionX-Tenvio-TimestampX-Tenvio-SignatureO receptor do kit implementa validação temporal, comparação em tempo constante, SQLite, deduplicação entre reinícios e estados monotônicos.
Envie uma mensagem ou resposta
Crie uma Idempotency-Key por intenção e reutilize a mesma chave e o mesmo corpo após timeout ou HTTP 503. Nunca gere outra chave automaticamente durante um retry.
curl "https://api.tenvioapi.com.br/v1/instances/$TENVIO_INSTANCE_ID/messages" -X POST -H "Authorization: Bearer $TENVIO_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: resposta-atendimento-0001" -d '{
"type": "reply",
"to": "DESTINO_RECEBIDO_PELO_CONECTOR",
"payload": {
"messageId": "ID_DA_MENSAGEM_RECEBIDA",
"text": "Olá! Como posso ajudar?"
}
}'{
"id": "00000000-0000-4000-8000-000000000001",
"status": "submitted",
"correlationId": "00000000-0000-4000-8000-000000000002"
}submitted não significa entregaEsse estado confirma apenas que o worker aceitou a submissão. Use a consulta ou os eventos message.delivered, message.read e message.failed para conhecer o resultado.
Consulte o estado do envio
curl "https://api.tenvioapi.com.br/v1/messages/ID_DA_MENSAGEM" -H "Authorization: Bearer $TENVIO_API_KEY" -H "Accept: application/json"acceptedmetadados aceitossubmittedmotor confirmou submissãosentacknowledgement de enviodeliveredentregue ao dispositivoreadleitura confirmada
failed é terminal. Eventos atrasados são preservados, mas nunca fazem o estado regredir.
Endpoints essenciais
/v1/instancesinstances:read/v1/instances/{id}instances:read/v1/instances/{id}/messagesmessages:write/v1/messages/{id}messages:read/v1/instances/{id}/messagesmessages:read/v1/webhookswebhooks:manage/v1/webhook-deliverieswebhooks:manage/v1/webhook-deliveries/{id}/replaywebhooks:replayComo sua aplicação deve reagir
400Requisição inválidaCorrija campos ou identificadores.
401Credencial inválidaSubstitua ou rotacione a chave.
403Escopo insuficienteCrie uma chave com a permissão necessária.
404Não encontradoNão diferencia recurso externo.
409Conflito idempotenteNão repita com corpo diferente.
429Limite temporárioRespeite Retry-After.
503Temporariamente indisponívelRepita mesma chave e mesmo corpo.
Execute sem dependências internas
O kit usa somente Node.js e os contratos públicos. Baixe os quatro arquivos na mesma pasta e execute a jornada sintética. Ela cria recursos temporários locais, comprova recebimento, deduplicação, resposta idempotente e conciliação, e remove tudo ao terminar.
node jornada-clean-room.mjsA jornada sintética não acessa a internet, não usa credenciais e não envia mensagens. Para uma integração real, configure o receptor atrás de HTTPS e use variáveis de ambiente protegidas.