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
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ão | Libera |
|---|---|
inboxes:read | Listar as inboxes (canais) da conta. |
contacts:read | Listar e consultar contatos. |
contacts:manage | Criar e atualizar contatos. |
custom-attributes:read | Listar os atributos personalizados. |
conversations:read | Listar e consultar conversas e o histórico de mensagens. |
conversations:manage | Iniciar, atualizar (resolver, reabrir, atribuir, adiar) e etiquetar conversas, enviar mensagens e templates. |
conversations:read-all | Acessar as conversas de todas as inboxes (chave sem restrição de inbox). |
labels:read | Listar as etiquetas. |
templates:read | Listar 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"
}| Status | Quando acontece | Códigos |
|---|---|---|
| 400 | Campo inválido ou regra de negócio violada. | CONTACT_PHONE_INVALIDCONTACT_ATTRIBUTE_UNKNOWN |
| 401 | Chave ausente, malformada, revogada ou expirada. | API_KEY_MISSINGAPI_KEY_INVALID |
| 402 | A conta tem pagamento pendente; o acesso fica bloqueado até a regularização. | ACCOUNT_PAYMENT_REQUIRED |
| 403 | A chave não tem a permissão exigida pela operação. | API_KEY_INSUFFICIENT_PERMISSION |
| 404 | O recurso não existe, é de outra conta ou está fora das inboxes da chave. | CONTACT_NOT_FOUNDCONVERSATION_NOT_FOUND |
| 409 | Conflito com o estado atual do recurso. | CONTACT_PHONE_EXISTSIDEMPOTENCY_REQUEST_IN_PROGRESS |
| 422 | Chave de idempotência reutilizada com outro corpo. | IDEMPOTENCY_KEY_REUSED |
| 429 | Limite 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: 1768484760Ao 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: trueRepetir 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.
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"
}'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."
}'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
}'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"
}
}'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"
}'