Pular para o conteúdo
talkvend

Desenvolvedores

API de integração

Conecte seu ERP, CRM, e-commerce ou BI à sua conta TalkVend: contatos, conversas, mensagens e templates do WhatsApp, de servidor para servidor.

Visão geral

A API de integração é REST com JSON e foi feita para chamadas servidor → servidor. Todas as rotas ficam sob a base URL abaixo; as datas seguem ISO 8601 em UTC e os ids são UUIDs.

Base URL: https://api.talkvend.com/v1

Ver a referência completa dos endpoints →

Autenticação

Crie uma chave em Configurações → Chaves de API no TalkVend e envie-a em todas as requisições no header Authorization, como bearer token. A chave completa aparece uma única vez, na criação; guarde-a num cofre de segredos ou variável de ambiente.

Authorization: Bearer vk_live_XXXXXXXXXXXX_...

Para conferir a chave, chame GET /integrations/me: a resposta traz a conta, o nome e as permissões da chave, as inboxes às quais ela está restrita e os limites de requisição.

curl 'https://api.talkvend.com/v1/integrations/me' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'

Permissões e escopo

Cada chave tem as próprias permissões. A referência mostra a permissão exigida por operação; sem ela a API responde 403 API_KEY_INSUFFICIENT_PERMISSION.

PermissãoLibera
inboxes:readListar as inboxes (canais) da conta.
contacts:readListar e consultar contatos.
contacts:manageCriar e atualizar contatos.
custom-attributes:readListar os atributos personalizados.
conversations:readListar e consultar conversas e o histórico de mensagens.
conversations:manageIniciar, atualizar (resolver, reabrir, atribuir, adiar) e etiquetar conversas, enviar mensagens e templates.
conversations:read-allAcessar as conversas de todas as inboxes (chave sem restrição de inbox).
labels:readListar as etiquetas.
templates:readListar os templates do WhatsApp.

Uma chave pode ser restrita a algumas inboxes: conversas fora delas se comportam como inexistentes (404).

Contatos pertencem à conta inteira e não são filtrados pelas inboxes da chave.

Erros

Erros respondem code e message. O code é estável e legível por máquina: mapeie-o para as suas próprias mensagens em vez de exibir o texto da API.

{
  "code": "CONVERSATION_NOT_FOUND",
  "message": "CONVERSATION_NOT_FOUND"
}

Falhas de validação de campos (400) usam outro formato, com um item por campo rejeitado:

{
  "statusCode": 400,
  "message": [
    "limit must not be greater than 100"
  ],
  "error": "Bad Request"
}
StatusQuando aconteceCódigos
400Campo inválido ou regra de negócio violada.CONTACT_PHONE_INVALIDCONTACT_ATTRIBUTE_UNKNOWN
401Chave ausente, malformada, revogada ou expirada.API_KEY_MISSINGAPI_KEY_INVALID
402A conta tem pagamento pendente; o acesso fica bloqueado até a regularização.ACCOUNT_PAYMENT_REQUIRED
403A chave não tem a permissão exigida pela operação.API_KEY_INSUFFICIENT_PERMISSION
404O recurso não existe, é de outra conta ou está fora das inboxes da chave.CONTACT_NOT_FOUNDCONVERSATION_NOT_FOUND
409Conflito com o estado atual do recurso.CONTACT_PHONE_EXISTSIDEMPOTENCY_REQUEST_IN_PROGRESS
422Chave de idempotência reutilizada com outro corpo.IDEMPOTENCY_KEY_REUSED
429Limite de requisições excedido.API_KEY_RATE_LIMITED

Toda resposta traz X-Request-Id. Informe esse valor ao falar com o suporte.

Rate limit

Cada chave pode fazer 300 requisições por minuto (configurável até 1200), e todas as chaves de uma conta somam no máximo 1000 por minuto. Falhas de autenticação repetidas a partir do mesmo IP também são limitadas.

As respostas trazem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (horário Unix, em segundos, em que a janela reinicia). Um 429 traz Retry-After, em segundos.

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1768484760

Ao receber 429, espere o tempo de Retry-After antes de repetir e espalhe as chamadas em lote ao longo do minuto.

Paginação

Endpoints de lista recebem page (começa em 1) e limit (padrão 20, máximo 100) e respondem data e meta:

curl 'https://api.talkvend.com/v1/integrations/contacts?page=2&limit=100' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'

{
  "data": [ … ],
  "meta": { "page": 2, "limit": 100, "total": 342, "totalPages": 4 }
}

A ordem é fixa por recurso e está descrita em cada endpoint da referência (por exemplo, contatos dos mais novos para os mais antigos e mensagens em ordem cronológica).

A paginação é por offset: itens criados enquanto você percorre as páginas podem deslocá-las, e um item pode aparecer duas vezes ou ser pulado. Para sincronizações completas, deduplique pelo id.

Idempotência

Os três POSTs que enviam mensagens — iniciar conversa, enviar mensagem e enviar template — aceitam o header Idempotency-Key (1 a 255 caracteres, guardado por 24 horas). Use uma chave por operação lógica, como o id do pedido que gerou a mensagem.

-H 'Idempotency-Key: order-12345-shipped'

HTTP/1.1 201 Created
Idempotent-Replayed: true

Repetir com a mesma chave e o mesmo corpo devolve o resultado original, com o header Idempotent-Replayed: true, sem enviar de novo.

A mesma chave com outro corpo falha com 422 IDEMPOTENCY_KEY_REUSED; repetir enquanto a primeira requisição ainda está em andamento falha com 409 IDEMPOTENCY_REQUEST_IN_PROGRESS — tente de novo em instantes.

Mensagens e a janela de 24 horas

POST /integrations/conversations/{conversationId}/messages envia texto numa conversa existente; com isPrivate: true vira nota interna, visível só para a equipe.

No WhatsApp, mensagens livres só podem ser enviadas até 24 horas depois da última mensagem do contato. Fora dessa janela, o único caminho é um template aprovado pela Meta.

Liste os templates aprovados com GET /integrations/templates e envie com POST /integrations/templates/{templateId}/send, passando os valores das variáveis por nome em parameters. O envio aceita três formas de destino:

  • conversationId — numa conversa existente;
  • inboxId + contactId — para um contato já cadastrado;
  • inboxId + contact — o contato é encontrado pelo telefone ou criado.

Exemplos

Os exemplos usam dados fictícios. Substitua a chave e os ids pelos da sua conta.

Criar um contato
curl -X POST 'https://api.talkvend.com/v1/integrations/contacts' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Maria Silva",
  "phoneNumber": "+55 11 90000-0000",
  "email": "cliente@exemplo.com",
  "identifier": "crm-000123"
}'
Iniciar uma conversa (idempotente)
curl -X POST 'https://api.talkvend.com/v1/integrations/conversations' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...' \
  -H 'Idempotency-Key: order-12345-shipped' \
  -H 'Content-Type: application/json' \
  -d '{
  "inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
  "contact": {
    "name": "Maria Silva",
    "phoneNumber": "+55 11 90000-0000"
  },
  "content": "Olá, Maria! Seu pedido #1234 está pronto para retirada."
}'
Responder numa conversa
curl -X POST 'https://api.talkvend.com/v1/integrations/conversations/4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c/messages' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...' \
  -H 'Idempotency-Key: order-12345-reply-1' \
  -H 'Content-Type: application/json' \
  -d '{
  "content": "Seu pedido saiu para entrega.",
  "isPrivate": false
}'
Enviar um template fora da janela de 24 horas
curl -X POST 'https://api.talkvend.com/v1/integrations/templates/7c8d9e0f-1a2b-4c3d-8e5f-6a7b8c9d0e1f/send' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...' \
  -H 'Idempotency-Key: order-12345-template' \
  -H 'Content-Type: application/json' \
  -d '{
  "inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
  "contact": {
    "name": "Maria Silva",
    "phoneNumber": "+55 11 90000-0000"
  },
  "parameters": {
    "client_name": "Maria"
  }
}'
Resolver uma conversa
curl -X PATCH 'https://api.talkvend.com/v1/integrations/conversations/4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "RESOLVED"
}'