Skip to content
talkvend

Developers

Integration API

Connect your ERP, CRM, e-commerce or BI to your TalkVend account: contacts, conversations, messages and WhatsApp templates, server to server.

Overview

The integration API is REST with JSON and is built for server → server calls. Every route lives under the base URL below; dates are ISO 8601 in UTC and ids are UUIDs.

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

See the complete endpoint reference →

Authentication

Create a key in Settings → API keys in TalkVend and send it on every request in the Authorization header, as a bearer token. The full key is shown only once, when it is created; keep it in a secret manager or environment variable.

Authorization: Bearer vk_live_XXXXXXXXXXXX_...

To check a key, call GET /integrations/me: the response has the account, the key name and permissions, the inboxes the key is restricted to and its rate limits.

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

Permissions and scope

Each key has its own permissions. The reference shows the permission each operation requires; without it the API answers 403 API_KEY_INSUFFICIENT_PERMISSION.

PermissionAllows
inboxes:readList the account inboxes (channels).
contacts:readList and read contacts.
contacts:manageCreate and update contacts.
custom-attributes:readList custom attributes.
conversations:readList and read conversations and their message history.
conversations:manageStart, update (resolve, reopen, assign, snooze) and label conversations, send messages and templates.
conversations:read-allAccess conversations of every inbox (key not restricted to inboxes).
labels:readList labels.
templates:readList WhatsApp templates.

A key may be restricted to some inboxes: conversations outside them behave as if they did not exist (404).

Contacts belong to the whole account and are not filtered by the inboxes of the key.

Errors

Errors answer code and message. The code is stable and machine-readable: map it to your own messages instead of showing the API text.

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

Field validation failures (400) use a different shape, with one entry per rejected field:

{
  "statusCode": 400,
  "message": [
    "limit must not be greater than 100"
  ],
  "error": "Bad Request"
}
StatusWhen it happensCodes
400Invalid field or broken business rule.CONTACT_PHONE_INVALIDCONTACT_ATTRIBUTE_UNKNOWN
401Missing, malformed, revoked or expired key.API_KEY_MISSINGAPI_KEY_INVALID
402The account has a pending payment; access is blocked until it is settled.ACCOUNT_PAYMENT_REQUIRED
403The key lacks the permission the operation requires.API_KEY_INSUFFICIENT_PERMISSION
404The resource does not exist, belongs to another account or is outside the inboxes of the key.CONTACT_NOT_FOUNDCONVERSATION_NOT_FOUND
409Conflict with the current state of the resource.CONTACT_PHONE_EXISTSIDEMPOTENCY_REQUEST_IN_PROGRESS
422Idempotency key reused with a different body.IDEMPOTENCY_KEY_REUSED
429Rate limit exceeded.API_KEY_RATE_LIMITED

Every response carries X-Request-Id. Include it when contacting support.

Rate limits

Each key can make 300 requests per minute (configurable up to 1200), and all keys of an account add up to at most 1000 per minute. Repeated authentication failures from the same IP are also throttled.

Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time, in seconds, when the window resets). A 429 carries Retry-After, in seconds.

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

On a 429, wait for Retry-After before retrying and spread batch calls across the minute.

Pagination

List endpoints take page (1-based) and limit (default 20, max 100) and answer data and 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 }
}

The order is fixed per resource and described on each endpoint of the reference (for example, contacts newest first and messages in chronological order).

Pagination is offset-based: items created while you walk the pages can shift them, so an item may show up twice or be skipped. For full syncs, deduplicate by id.

Idempotency

The three POSTs that send messages — start a conversation, send a message and send a template — accept the Idempotency-Key header (1 to 255 characters, kept for 24 hours). Use one key per logical operation, such as the id of the order that triggered the message.

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

HTTP/1.1 201 Created
Idempotent-Replayed: true

Retrying with the same key and body returns the original result, with the Idempotent-Replayed: true header, without sending again.

The same key with a different body fails with 422 IDEMPOTENCY_KEY_REUSED; retrying while the first request is still running fails with 409 IDEMPOTENCY_REQUEST_IN_PROGRESS — try again in a moment.

Messages and the 24-hour window

POST /integrations/conversations/{conversationId}/messages sends text to an existing conversation; with isPrivate: true it becomes an internal note, visible to your team only.

On WhatsApp, free-form messages can only be sent up to 24 hours after the contact's last message. Outside that window, the only way is a template approved by Meta.

List approved templates with GET /integrations/templates and send with POST /integrations/templates/{templateId}/send, passing variable values by name in parameters. Sending accepts three kinds of target:

  • conversationId — to an existing conversation;
  • inboxId + contactId — to a contact you already have;
  • inboxId + contact — the contact is found by phone number or created.

Examples

The examples use fictitious data. Replace the key and ids with the ones from your account.

Create a contact
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"
}'
Start a conversation (idempotent)
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."
}'
Reply in a conversation
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
}'
Send a template outside the 24-hour window
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"
  }
}'
Resolve a conversation
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"
}'