Tenvio APIDocumentação
OpenAPIAbrir painel

Integração sem conhecimento interno

Da credencial à primeira conversa.

Um caminho direto para receber mensagens, responder pela API e acompanhar cada envio. Exemplos em JavaScript e HTTP, sem SDK obrigatório.

URL base
https://api.tenvioapi.com.br/v1
Autenticação
Bearer token
Formato
JSON + webhooks HMAC

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.

  1. 1Crie a credencialEscolha o perfil CRM no painel.
  2. 2Descubra a instânciaConfirme que está pronta.
  3. 3Cadastre o webhookGuarde o segredo uma vez.
  4. 4Receba o eventoValide e persista antes do 2xx.
  5. 5Envie a respostaUse idempotência em todo envio.
  6. 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.

Variáveis de ambiente
TENVIO_API_KEY=tvk_PREFIXO.SEGREDO_EXIBIDO_UMA_VEZ
TENVIO_INSTANCE_ID=00000000-0000-4000-8000-000000000000
TENVIO_API_URL=https://api.tenvioapi.com.br
Segredos de exibição única

A 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.

1

Obtenha sua credencial

  1. Entre no painel da Tenvio e abra Integrações.
  2. Em Credenciais, selecione Criar credencial.
  3. Use Selecionar perfil CRM para marcar os cinco escopos abaixo.
  4. Copie a chave exibida e guarde-a fora do código.
instances:readmessages:readmessages:writewebhooks:managewebhooks:replay

Para integrações menores, remova escopos que não serão usados. Uma credencial sem o escopo exigido recebe HTTP 403.

2

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.

Listar instâncias
curl https://api.tenvioapi.com.br/v1/instances   -H "Authorization: Bearer $TENVIO_API_KEY"   -H "Accept: application/json"
Resposta 200
{
  "data": [{
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Atendimento",
    "sessionStatus": "authenticated",
    "deviceStatus": "online",
    "readyForMessages": true
  }]
}
3

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.

Pelo painel: Integrações → Configurar webhookPela API:
Criar endpoint
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"
    ]
  }'
Antes de responder 2xx

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.

4

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.

Validar assinatura em JavaScript
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)
}
Cabeçalhos obrigatóriosX-Tenvio-Delivery-IdX-Tenvio-Event-IdX-Tenvio-Event-VersionX-Tenvio-TimestampX-Tenvio-Signature

O receptor do kit implementa validação temporal, comparação em tempo constante, SQLite, deduplicação entre reinícios e estados monotônicos.

5

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.

Responder à mensagem recebida
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?"
    }
  }'
Resposta 202
{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "submitted",
  "correlationId": "00000000-0000-4000-8000-000000000002"
}
submitted não significa entrega

Esse 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.

6

Consulte o estado do envio

Consultar mensagem
curl "https://api.tenvioapi.com.br/v1/messages/ID_DA_MENSAGEM"   -H "Authorization: Bearer $TENVIO_API_KEY"   -H "Accept: application/json"
  1. acceptedmetadados aceitos
  2. submittedmotor confirmou submissão
  3. sentacknowledgement de envio
  4. deliveredentregue ao dispositivo
  5. readleitura confirmada

failed é terminal. Eventos atrasados são preservados, mas nunca fazem o estado regredir.

Endpoints essenciais

MétodoCaminhoEscopo
GET/v1/instancesinstances:read
GET/v1/instances/{id}instances:read
POST/v1/instances/{id}/messagesmessages:write
GET/v1/messages/{id}messages:read
GET/v1/instances/{id}/messagesmessages:read
POST/v1/webhookswebhooks:manage
GET/v1/webhook-deliverieswebhooks:manage
POST/v1/webhook-deliveries/{id}/replaywebhooks:replay

Baixar o contrato OpenAPI 3.1 completo →

Como sua aplicação deve reagir

400Requisição inválida

Corrija campos ou identificadores.

401Credencial inválida

Substitua ou rotacione a chave.

403Escopo insuficiente

Crie uma chave com a permissão necessária.

404Não encontrado

Não diferencia recurso externo.

409Conflito idempotente

Não repita com corpo diferente.

429Limite temporário

Respeite Retry-After.

503Temporariamente indisponível

Repita 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.

Executar a prova local
node jornada-clean-room.mjs

A 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.