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
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.
| Permission | Allows |
|---|---|
inboxes:read | List the account inboxes (channels). |
contacts:read | List and read contacts. |
contacts:manage | Create and update contacts. |
custom-attributes:read | List custom attributes. |
conversations:read | List and read conversations and their message history. |
conversations:manage | Start, update (resolve, reopen, assign, snooze) and label conversations, send messages and templates. |
conversations:read-all | Access conversations of every inbox (key not restricted to inboxes). |
labels:read | List labels. |
templates:read | List 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"
}| Status | When it happens | Codes |
|---|---|---|
| 400 | Invalid field or broken business rule. | CONTACT_PHONE_INVALIDCONTACT_ATTRIBUTE_UNKNOWN |
| 401 | Missing, malformed, revoked or expired key. | API_KEY_MISSINGAPI_KEY_INVALID |
| 402 | The account has a pending payment; access is blocked until it is settled. | ACCOUNT_PAYMENT_REQUIRED |
| 403 | The key lacks the permission the operation requires. | API_KEY_INSUFFICIENT_PERMISSION |
| 404 | The resource does not exist, belongs to another account or is outside the inboxes of the key. | CONTACT_NOT_FOUNDCONVERSATION_NOT_FOUND |
| 409 | Conflict with the current state of the resource. | CONTACT_PHONE_EXISTSIDEMPOTENCY_REQUEST_IN_PROGRESS |
| 422 | Idempotency key reused with a different body. | IDEMPOTENCY_KEY_REUSED |
| 429 | Rate 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: 1768484760On 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: trueRetrying 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.
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"
}'