API reference
vend Integration API
v1.0.0Base URL: https://api.talkvend.com/v1
Server-to-server API for integrating your systems (ERP, CRM, e-commerce, BI) with your vend account.
Authentication
Create an API key in Settings → API keys and send it as a bearer token:
Authorization: Bearer vk_live_XXXXXXXXXXXX_...
Each key has its own permissions (shown per operation as x-vend-permission) and may be restricted to some inboxes: conversations outside them behave as if they did not exist (404). Contacts are account-wide.
Keys are secrets. Never ship them in a browser or mobile app — this API has no CORS support on purpose.
Pagination
List endpoints take page (1-based) and limit (default 20, max 100) and answer { data, meta: { page, limit, total, totalPages } }. Pagination is offset-based and not stable for a full scan: items created (or, for conversations, with new activity) while you walk the pages can shift them, so the same item may show up twice or be skipped. When syncing, de-duplicate by id and re-read the first pages at the end.
Rate limits
300 requests/minute per key (configurable up to 1200) and 1000 requests/minute per account. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 carries Retry-After. Repeated authentication failures from the same IP are also throttled.
Idempotency
POST /integrations/conversations, POST /integrations/conversations/{conversationId}/messages and POST /integrations/templates/{templateId}/send accept an Idempotency-Key header (1–255 characters, kept for 24 hours). Retrying with the same key and body returns the original result with Idempotent-Replayed: true; the same key with a different body fails with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first request is still running fails with 409 IDEMPOTENCY_REQUEST_IN_PROGRESS. Once the message is stored, every retry is a replay — it is never sent twice. If the first request failed with an error code before that point, the key is free for an immediate retry; after an unexpected failure it stays IN_PROGRESS (409) for up to 15 minutes.
Errors
Errors answer { "code": "DOMAIN_DETAIL", "message": "DOMAIN_DETAIL" } — code is stable, map it to your own messages. Field validation failures (400) answer { "statusCode": 400, "message": ["..."], "error": "Bad Request" } instead.
Me
/integrations/meInspect the current API key
Returns the key, its account, permissions, inbox restriction and rate limits. Requires no permission: use it to test a key.
Responses
200The API key used in this request.
The API key used in this request.
| Name | Type | Description |
|---|---|---|
apiKeyrequired | IntegrationMeApiKey | |
accountrequired | IntegrationNamedRef | |
allInboxesrequired | boolean | True when the key is not restricted to specific inboxes (requires |
inboxesrequired | array<IntegrationNamedRef> | Inboxes the key is restricted to (empty when |
rateLimitrequired | IntegrationMeRateLimit |
{
"apiKey": {
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"name": "ERP integration",
"prefix": "vk_live_XXXXXXXXXXXX",
"permissions": [
"contacts:read",
"conversations:manage",
"conversations:read"
]
},
"account": {
"id": "0b9a6c1e-1f6d-4c4a-9a51-6f1d2b3c4d5e",
"name": "Acme Ltda"
},
"allInboxes": false,
"inboxes": [
{
"id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"name": "Support WhatsApp"
}
],
"rateLimit": {
"perMinute": 300,
"accountPerMinute": 1000
}
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl 'https://api.talkvend.com/v1/integrations/me' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'Inboxes
/integrations/inboxesList inboxes
inboxes:readInboxes the key can use: only the ones it is restricted to, if any.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
pageoptional | query | integer | 1-based page number. Default: min 1 |
limitoptional | query | integer | Items per page (max 100). Default: min 1 · max 100 |
Responses
200A page of inboxes.
A page of inboxes.
| Name | Type | Description |
|---|---|---|
datarequired | array<IntegrationInbox> | |
metarequired | IntegrationPageMeta |
{
"data": [
{
"id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"name": "Support WhatsApp",
"channelType": "WHATSAPP_CLOUD",
"active": true
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 42,
"totalPages": 3
}
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
| Name | Type | Description |
|---|---|---|
statusCoderequired | number | |
messagerequired | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorrequired | string |
Examples
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl 'https://api.talkvend.com/v1/integrations/inboxes' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'Contacts
/integrations/contactsList contacts
contacts:readContacts of the whole account (not restricted by the inboxes of the key), newest first.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
searchoptional | query | string | Substring of the name, phone number or e-mail. length 0–120 |
pageoptional | query | integer | 1-based page number. Default: min 1 |
limitoptional | query | integer | Items per page (max 100). Default: min 1 · max 100 |
Responses
200A page of contacts.
A page of contacts.
| Name | Type | Description |
|---|---|---|
datarequired | array<IntegrationContact> | |
metarequired | IntegrationPageMeta |
{
"data": [
{
"id": "3e4f5a6b-7c8d-4e9f-8a1b-2c3d4e5f6a7b",
"name": "Maria Silva",
"phoneNumber": "+5511900000000",
"email": "cliente@exemplo.com",
"identifier": "crm-000123",
"customAttributes": {
"plan": "silver"
},
"createdAt": "2026-01-15T13:45:00.000Z",
"updatedAt": "2026-01-15T13:45:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 42,
"totalPages": 3
}
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
| Name | Type | Description |
|---|---|---|
statusCoderequired | number | |
messagerequired | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorrequired | string |
Examples
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl 'https://api.talkvend.com/v1/integrations/contacts' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'/integrations/contactsCreate a contact
contacts:managePhone numbers are normalized to E.164. customAttributes keys must exist in GET /integrations/custom-attributes.
Request body (application/json)
| Name | Type | Description |
|---|---|---|
namerequired | string | length 1–120 |
phoneNumberoptional | string | Phone in international format; stored as E.164. length 1–32 |
emailoptional | string · email | length 0–255 |
identifieroptional | string | Your own identifier for this contact (e.g. CRM id). length 0–255 |
customAttributesoptional | object | Values keyed by custom attribute |
Responses
201The created contact.
The created contact.
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
namerequired | stringnullable | |
phoneNumberrequired | stringnullable | E.164 with |
emailrequired | string · emailnullable | |
identifierrequired | stringnullable | Your own identifier for this contact (e.g. CRM id). |
customAttributesrequired | object | Values keyed by custom attribute |
createdAtrequired | string · date-time | |
updatedAtrequired | string · date-time |
{
"id": "3e4f5a6b-7c8d-4e9f-8a1b-2c3d4e5f6a7b",
"name": "Maria Silva",
"phoneNumber": "+5511900000000",
"email": "cliente@exemplo.com",
"identifier": "crm-000123",
"customAttributes": {
"plan": "silver"
},
"createdAt": "2026-01-15T13:45:00.000Z",
"updatedAt": "2026-01-15T13:45:00.000Z"
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Examples
{
"code": "CONTACT_ATTRIBUTE_INVALID",
"message": "CONTACT_ATTRIBUTE_INVALID"
}{
"code": "CONTACT_ATTRIBUTE_UNKNOWN",
"message": "CONTACT_ATTRIBUTE_UNKNOWN"
}{
"code": "CONTACT_PHONE_INVALID",
"message": "CONTACT_PHONE_INVALID"
}{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
409The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "CONTACT_PHONE_EXISTS",
"message": "CONTACT_PHONE_EXISTS"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
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",
"customAttributes": {
"plan": "silver"
}
}'/integrations/contacts/{contactId}Get a contact
contacts:readParameters
| Name | In | Type | Description |
|---|---|---|---|
contactIdrequired | path | string · uuid |
Responses
200The contact.
The contact.
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
namerequired | stringnullable | |
phoneNumberrequired | stringnullable | E.164 with |
emailrequired | string · emailnullable | |
identifierrequired | stringnullable | Your own identifier for this contact (e.g. CRM id). |
customAttributesrequired | object | Values keyed by custom attribute |
createdAtrequired | string · date-time | |
updatedAtrequired | string · date-time |
{
"id": "3e4f5a6b-7c8d-4e9f-8a1b-2c3d4e5f6a7b",
"name": "Maria Silva",
"phoneNumber": "+5511900000000",
"email": "cliente@exemplo.com",
"identifier": "crm-000123",
"customAttributes": {
"plan": "silver"
},
"createdAt": "2026-01-15T13:45:00.000Z",
"updatedAt": "2026-01-15T13:45:00.000Z"
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
| Name | Type | Description |
|---|---|---|
statusCoderequired | number | |
messagerequired | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorrequired | string |
Examples
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
404The resource does not exist, belongs to another account or is outside the inboxes of the key.
The resource does not exist, belongs to another account or is outside the inboxes of the key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "CONTACT_NOT_FOUND",
"message": "CONTACT_NOT_FOUND"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl 'https://api.talkvend.com/v1/integrations/contacts/00000000-0000-0000-0000-000000000000' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'/integrations/contacts/{contactId}Update a contact
contacts:manageOnly the fields sent are changed.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
contactIdrequired | path | string · uuid |
Request body (application/json)
| Name | Type | Description |
|---|---|---|
nameoptional | string | length 1–120 |
phoneNumberoptional | string | Phone in international format; stored as E.164. length 1–32 |
emailoptional | string · emailnullable |
length 0–255 |
identifieroptional | stringnullable | Your own identifier for this contact; length 0–255 |
customAttributesoptional | object | Values keyed by custom attribute |
Responses
200The updated contact.
The updated contact.
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
namerequired | stringnullable | |
phoneNumberrequired | stringnullable | E.164 with |
emailrequired | string · emailnullable | |
identifierrequired | stringnullable | Your own identifier for this contact (e.g. CRM id). |
customAttributesrequired | object | Values keyed by custom attribute |
createdAtrequired | string · date-time | |
updatedAtrequired | string · date-time |
{
"id": "3e4f5a6b-7c8d-4e9f-8a1b-2c3d4e5f6a7b",
"name": "Maria Silva",
"phoneNumber": "+5511900000000",
"email": "cliente@exemplo.com",
"identifier": "crm-000123",
"customAttributes": {
"plan": "silver"
},
"createdAt": "2026-01-15T13:45:00.000Z",
"updatedAt": "2026-01-15T13:45:00.000Z"
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Examples
{
"code": "CONTACT_ATTRIBUTE_INVALID",
"message": "CONTACT_ATTRIBUTE_INVALID"
}{
"code": "CONTACT_ATTRIBUTE_UNKNOWN",
"message": "CONTACT_ATTRIBUTE_UNKNOWN"
}{
"code": "CONTACT_PHONE_INVALID",
"message": "CONTACT_PHONE_INVALID"
}{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
404The resource does not exist, belongs to another account or is outside the inboxes of the key.
The resource does not exist, belongs to another account or is outside the inboxes of the key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "CONTACT_NOT_FOUND",
"message": "CONTACT_NOT_FOUND"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
409The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "CONTACT_PHONE_EXISTS",
"message": "CONTACT_PHONE_EXISTS"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl -X PATCH 'https://api.talkvend.com/v1/integrations/contacts/00000000-0000-0000-0000-000000000000' \
-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",
"customAttributes": {
"plan": "gold"
}
}'Custom attributes
/integrations/custom-attributesList custom attributes
custom-attributes:readCustom attribute definitions: the keys accepted in customAttributes.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
modeloptional | query | CustomAttributeModel | Values: |
pageoptional | query | integer | 1-based page number. Default: min 1 |
limitoptional | query | integer | Items per page (max 100). Default: min 1 · max 100 |
Responses
200A page of custom attribute definitions.
A page of custom attribute definitions.
| Name | Type | Description |
|---|---|---|
datarequired | array<IntegrationCustomAttribute> | |
metarequired | IntegrationPageMeta |
{
"data": [
{
"id": "8d9e0f1a-2b3c-4d4e-9f6a-7b8c9d0e1f2a",
"key": "plan",
"displayName": "Plan",
"model": "CONTACT",
"type": "LIST",
"values": [
"bronze",
"silver",
"gold"
]
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 42,
"totalPages": 3
}
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
| Name | Type | Description |
|---|---|---|
statusCoderequired | number | |
messagerequired | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorrequired | string |
Examples
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl 'https://api.talkvend.com/v1/integrations/custom-attributes' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'Conversations
/integrations/conversationsList conversations
conversations:readConversations in the inboxes of the key. Order: most recent activity first; with status=SNOOZED, soonest wake-up first; with status=RESOLVED, most recently resolved first. Not stable for a full scan: a conversation with new activity jumps to the first page while you paginate — de-duplicate by id.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
statusoptional | query | ConversationStatus | Values: |
inboxIdoptional | query | string · uuid | |
contactIdoptional | query | string · uuid | |
assigneeIdoptional | query | string · uuid | |
labelIdoptional | query | string · uuid | |
pageoptional | query | integer | 1-based page number. Default: min 1 |
limitoptional | query | integer | Items per page (max 100). Default: min 1 · max 100 |
Responses
200A page of conversations.
A page of conversations.
| Name | Type | Description |
|---|---|---|
datarequired | array<IntegrationConversation> | |
metarequired | IntegrationPageMeta |
{
"data": [
{
"id": "4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c",
"displayId": 128,
"inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"contactId": "3e4f5a6b-7c8d-4e9f-8a1b-2c3d4e5f6a7b",
"status": "OPEN",
"assigneeId": "9e0f1a2b-3c4d-4e5f-8a7b-8c9d0e1f2a3b",
"snoozedUntil": null,
"resolvedAt": null,
"lastActivityAt": "2026-01-15T13:45:00.000Z",
"subject": null,
"labels": [
{
"id": "6b7c8d9e-0f1a-4b2c-9d4e-5f6a7b8c9d0e",
"title": "billing"
}
],
"createdAt": "2026-01-15T13:45:00.000Z",
"updatedAt": "2026-01-15T13:45:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 42,
"totalPages": 3
}
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
| Name | Type | Description |
|---|---|---|
statusCoderequired | number | |
messagerequired | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorrequired | string |
Examples
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl 'https://api.talkvend.com/v1/integrations/conversations' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'/integrations/conversationsStart a conversation with a first message
conversations:manageIdempotentSends a free-text message to a contact (contactId, or contact to find-or-create by phone/e-mail). Reuses the open conversation of that contact in the inbox when there is one (created: false). Always answers 201. WhatsApp Cloud inboxes require a template outside the 24 h window: use POST /integrations/templates/{templateId}/send.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Keyoptional | header | string |
length 1–255 |
Request body (application/json)
IntegrationCreateConversationDto
| Name | Type | Description |
|---|---|---|
inboxIdrequired | string · uuid | |
contactIdoptional | string · uuid | Existing contact. Send exactly one of |
contactoptional | IntegrationConversationContactInput | Contact to find or create. Send exactly one of |
contentrequired | string | length 1–100000 |
subjectoptional | string | Required for e-mail inboxes; ignored by other channels. length 1–998 |
assigneeIdoptional | string · uuid | User to assign a new conversation to (active member of the inbox). Without it the conversation stays unassigned. |
Responses
201The conversation and the message sent.
The conversation and the message sent.
IntegrationCreateConversationResult
| Name | Type | Description |
|---|---|---|
conversationrequired | IntegrationConversation | |
messagerequired | IntegrationMessage | |
createdrequired | boolean | False when an open conversation with this contact in this inbox was reused. |
{
"conversation": {
"id": "4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c",
"displayId": 128,
"inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"contactId": "3e4f5a6b-7c8d-4e9f-8a1b-2c3d4e5f6a7b",
"status": "OPEN",
"assigneeId": "9e0f1a2b-3c4d-4e5f-8a7b-8c9d0e1f2a3b",
"snoozedUntil": null,
"resolvedAt": null,
"lastActivityAt": "2026-01-15T13:45:00.000Z",
"subject": null,
"labels": [
{
"id": "6b7c8d9e-0f1a-4b2c-9d4e-5f6a7b8c9d0e",
"title": "billing"
}
],
"createdAt": "2026-01-15T13:45:00.000Z",
"updatedAt": "2026-01-15T13:45:00.000Z"
},
"message": {
"id": "5a6b7c8d-9e0f-4a1b-8c3d-4e5f6a7b8c9d",
"conversationId": "4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c",
"inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"type": "OUTGOING",
"contentType": "TEXT",
"status": "SENT",
"content": "Hello! Your order has shipped.",
"private": false,
"sender": {
"kind": "API_KEY",
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"name": "ERP integration"
},
"createdAt": "2026-01-15T13:45:00.000Z"
},
"created": true
}Response headers
- Idempotent-Replayed string
Present (
true) when this response replays the result of an earlier request with the sameIdempotency-Key.- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Examples
{
"code": "CONTACT_PHONE_INVALID",
"message": "CONTACT_PHONE_INVALID"
}{
"code": "CONVERSATION_ASSIGNEE_NOT_IN_INBOX",
"message": "CONVERSATION_ASSIGNEE_NOT_IN_INBOX"
}{
"code": "CONVERSATION_TARGET_INVALID",
"message": "CONVERSATION_TARGET_INVALID"
}{
"code": "EMAIL_SUBJECT_REQUIRED",
"message": "EMAIL_SUBJECT_REQUIRED"
}{
"code": "IDEMPOTENCY_KEY_INVALID",
"message": "IDEMPOTENCY_KEY_INVALID"
}{
"code": "INBOX_CHANNEL_UNSUPPORTED",
"message": "INBOX_CHANNEL_UNSUPPORTED"
}{
"code": "MESSAGE_CONTENT_TOO_LONG",
"message": "MESSAGE_CONTENT_TOO_LONG"
}{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
404The resource does not exist, belongs to another account or is outside the inboxes of the key.
The resource does not exist, belongs to another account or is outside the inboxes of the key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "CONTACT_NOT_FOUND",
"message": "CONTACT_NOT_FOUND"
}{
"code": "INBOX_NOT_FOUND",
"message": "INBOX_NOT_FOUND"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
409The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
"message": "IDEMPOTENCY_REQUEST_IN_PROGRESS"
}{
"code": "INBOX_FREE_TEXT_BLOCKED",
"message": "INBOX_FREE_TEXT_BLOCKED"
}{
"code": "META_OUTSIDE_WINDOW",
"message": "META_OUTSIDE_WINDOW"
}{
"code": "WHATSAPP_OUTSIDE_WINDOW",
"message": "WHATSAPP_OUTSIDE_WINDOW"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
422The request is well-formed but cannot be processed.
The request is well-formed but cannot be processed.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "IDEMPOTENCY_KEY_REUSED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
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",
"contactId": "3e4f5a6b-7c8d-4e9f-8a1b-2c3d4e5f6a7b",
"contact": {
"name": "Maria Silva",
"phoneNumber": "+55 11 90000-0000",
"email": "cliente@exemplo.com",
"identifier": "crm-000123",
"customAttributes": {
"plan": "silver"
}
},
"content": "Hello Maria, your order #1234 is ready for pickup.",
"subject": "Your order #1234",
"assigneeId": "9e0f1a2b-3c4d-4e5f-8a7b-8c9d0e1f2a3b"
}'/integrations/conversations/{conversationId}Get a conversation
conversations:readParameters
| Name | In | Type | Description |
|---|---|---|---|
conversationIdrequired | path | string · uuid |
Responses
200The conversation.
The conversation.
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
displayIdrequired | number | Sequential number shown in the vend inbox. |
inboxIdrequired | string · uuid | |
contactIdrequired | string · uuid | |
statusrequired | ConversationStatus | Values: |
assigneeIdrequired | string · uuidnullable | |
snoozedUntilrequired | string · date-timenullable | |
resolvedAtrequired | string · date-timenullable | |
lastActivityAtrequired | string · date-time | |
subjectrequired | stringnullable | E-mail subject (e-mail inboxes only). |
labelsrequired | array<IntegrationConversationLabel> | |
createdAtrequired | string · date-time | |
updatedAtrequired | string · date-time |
{
"id": "4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c",
"displayId": 128,
"inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"contactId": "3e4f5a6b-7c8d-4e9f-8a1b-2c3d4e5f6a7b",
"status": "OPEN",
"assigneeId": "9e0f1a2b-3c4d-4e5f-8a7b-8c9d0e1f2a3b",
"snoozedUntil": null,
"resolvedAt": null,
"lastActivityAt": "2026-01-15T13:45:00.000Z",
"subject": null,
"labels": [
{
"id": "6b7c8d9e-0f1a-4b2c-9d4e-5f6a7b8c9d0e",
"title": "billing"
}
],
"createdAt": "2026-01-15T13:45:00.000Z",
"updatedAt": "2026-01-15T13:45:00.000Z"
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
| Name | Type | Description |
|---|---|---|
statusCoderequired | number | |
messagerequired | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorrequired | string |
Examples
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
404The resource does not exist, belongs to another account or is outside the inboxes of the key.
The resource does not exist, belongs to another account or is outside the inboxes of the key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl 'https://api.talkvend.com/v1/integrations/conversations/00000000-0000-0000-0000-000000000000' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'/integrations/conversations/{conversationId}Update a conversation
conversations:manageResolve, reopen, snooze or (un)assign. Assigning to a user who belongs to more than one segment fails with CONVERSATION_SEGMENT_REQUIRED: segments cannot be chosen through the API.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
conversationIdrequired | path | string · uuid |
Request body (application/json)
IntegrationUpdateConversationDto
| Name | Type | Description |
|---|---|---|
statusoptional | ConversationStatus | Values: |
assigneeIdoptional | string · uuidnullable | User to assign (must be an active member of the inbox); |
snoozedUntiloptional | string · date-timenullable | Snooze until this moment; |
Responses
200The updated conversation.
The updated conversation.
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
displayIdrequired | number | Sequential number shown in the vend inbox. |
inboxIdrequired | string · uuid | |
contactIdrequired | string · uuid | |
statusrequired | ConversationStatus | Values: |
assigneeIdrequired | string · uuidnullable | |
snoozedUntilrequired | string · date-timenullable | |
resolvedAtrequired | string · date-timenullable | |
lastActivityAtrequired | string · date-time | |
subjectrequired | stringnullable | E-mail subject (e-mail inboxes only). |
labelsrequired | array<IntegrationConversationLabel> | |
createdAtrequired | string · date-time | |
updatedAtrequired | string · date-time |
{
"id": "4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c",
"displayId": 128,
"inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"contactId": "3e4f5a6b-7c8d-4e9f-8a1b-2c3d4e5f6a7b",
"status": "OPEN",
"assigneeId": "9e0f1a2b-3c4d-4e5f-8a7b-8c9d0e1f2a3b",
"snoozedUntil": null,
"resolvedAt": null,
"lastActivityAt": "2026-01-15T13:45:00.000Z",
"subject": null,
"labels": [
{
"id": "6b7c8d9e-0f1a-4b2c-9d4e-5f6a7b8c9d0e",
"title": "billing"
}
],
"createdAt": "2026-01-15T13:45:00.000Z",
"updatedAt": "2026-01-15T13:45:00.000Z"
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Examples
{
"code": "CONVERSATION_ASSIGNEE_NOT_IN_INBOX",
"message": "CONVERSATION_ASSIGNEE_NOT_IN_INBOX"
}{
"code": "CONVERSATION_SEGMENT_REQUIRED",
"message": "CONVERSATION_SEGMENT_REQUIRED"
}{
"code": "CONVERSATION_SNOOZE_INVALID",
"message": "CONVERSATION_SNOOZE_INVALID"
}{
"code": "CONVERSATION_STATUS_INVALID",
"message": "CONVERSATION_STATUS_INVALID"
}{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
404The resource does not exist, belongs to another account or is outside the inboxes of the key.
The resource does not exist, belongs to another account or is outside the inboxes of the key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl -X PATCH 'https://api.talkvend.com/v1/integrations/conversations/00000000-0000-0000-0000-000000000000' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...' \
-H 'Content-Type: application/json' \
-d '{
"status": "RESOLVED",
"assigneeId": "9e0f1a2b-3c4d-4e5f-8a7b-8c9d0e1f2a3b",
"snoozedUntil": "2026-01-20T12:00:00.000Z"
}'/integrations/conversations/{conversationId}/labelsAdd a label to a conversation
conversations:manageParameters
| Name | In | Type | Description |
|---|---|---|---|
conversationIdrequired | path | string · uuid |
Request body (application/json)
| Name | Type | Description |
|---|---|---|
labelIdrequired | string · uuid |
Responses
200The conversation with its labels.
The conversation with its labels.
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
displayIdrequired | number | Sequential number shown in the vend inbox. |
inboxIdrequired | string · uuid | |
contactIdrequired | string · uuid | |
statusrequired | ConversationStatus | Values: |
assigneeIdrequired | string · uuidnullable | |
snoozedUntilrequired | string · date-timenullable | |
resolvedAtrequired | string · date-timenullable | |
lastActivityAtrequired | string · date-time | |
subjectrequired | stringnullable | E-mail subject (e-mail inboxes only). |
labelsrequired | array<IntegrationConversationLabel> | |
createdAtrequired | string · date-time | |
updatedAtrequired | string · date-time |
{
"id": "4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c",
"displayId": 128,
"inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"contactId": "3e4f5a6b-7c8d-4e9f-8a1b-2c3d4e5f6a7b",
"status": "OPEN",
"assigneeId": "9e0f1a2b-3c4d-4e5f-8a7b-8c9d0e1f2a3b",
"snoozedUntil": null,
"resolvedAt": null,
"lastActivityAt": "2026-01-15T13:45:00.000Z",
"subject": null,
"labels": [
{
"id": "6b7c8d9e-0f1a-4b2c-9d4e-5f6a7b8c9d0e",
"title": "billing"
}
],
"createdAt": "2026-01-15T13:45:00.000Z",
"updatedAt": "2026-01-15T13:45:00.000Z"
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
| Name | Type | Description |
|---|---|---|
statusCoderequired | number | |
messagerequired | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorrequired | string |
Examples
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
404The resource does not exist, belongs to another account or is outside the inboxes of the key.
The resource does not exist, belongs to another account or is outside the inboxes of the key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}{
"code": "LABEL_NOT_FOUND",
"message": "LABEL_NOT_FOUND"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
409The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "LABEL_CONVERSATION_ALREADY_EXISTS",
"message": "LABEL_CONVERSATION_ALREADY_EXISTS"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl -X POST 'https://api.talkvend.com/v1/integrations/conversations/00000000-0000-0000-0000-000000000000/labels' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...' \
-H 'Content-Type: application/json' \
-d '{
"labelId": "6b7c8d9e-0f1a-4b2c-9d4e-5f6a7b8c9d0e"
}'/integrations/conversations/{conversationId}/labels/{labelId}Remove a label from a conversation
conversations:manageParameters
| Name | In | Type | Description |
|---|---|---|---|
conversationIdrequired | path | string · uuid | |
labelIdrequired | path | string · uuid |
Responses
200The conversation with its labels.
The conversation with its labels.
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
displayIdrequired | number | Sequential number shown in the vend inbox. |
inboxIdrequired | string · uuid | |
contactIdrequired | string · uuid | |
statusrequired | ConversationStatus | Values: |
assigneeIdrequired | string · uuidnullable | |
snoozedUntilrequired | string · date-timenullable | |
resolvedAtrequired | string · date-timenullable | |
lastActivityAtrequired | string · date-time | |
subjectrequired | stringnullable | E-mail subject (e-mail inboxes only). |
labelsrequired | array<IntegrationConversationLabel> | |
createdAtrequired | string · date-time | |
updatedAtrequired | string · date-time |
{
"id": "4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c",
"displayId": 128,
"inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"contactId": "3e4f5a6b-7c8d-4e9f-8a1b-2c3d4e5f6a7b",
"status": "OPEN",
"assigneeId": "9e0f1a2b-3c4d-4e5f-8a7b-8c9d0e1f2a3b",
"snoozedUntil": null,
"resolvedAt": null,
"lastActivityAt": "2026-01-15T13:45:00.000Z",
"subject": null,
"labels": [
{
"id": "6b7c8d9e-0f1a-4b2c-9d4e-5f6a7b8c9d0e",
"title": "billing"
}
],
"createdAt": "2026-01-15T13:45:00.000Z",
"updatedAt": "2026-01-15T13:45:00.000Z"
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
| Name | Type | Description |
|---|---|---|
statusCoderequired | number | |
messagerequired | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorrequired | string |
Examples
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
404The resource does not exist, belongs to another account or is outside the inboxes of the key.
The resource does not exist, belongs to another account or is outside the inboxes of the key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}{
"code": "LABEL_CONVERSATION_NOT_FOUND",
"message": "LABEL_CONVERSATION_NOT_FOUND"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl -X DELETE 'https://api.talkvend.com/v1/integrations/conversations/00000000-0000-0000-0000-000000000000/labels/00000000-0000-0000-0000-000000000000' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'/integrations/conversations/{conversationId}/messagesList messages of a conversation
conversations:readOldest first.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
conversationIdrequired | path | string · uuid | |
pageoptional | query | integer | 1-based page number. Default: min 1 |
limitoptional | query | integer | Items per page (max 100). Default: min 1 · max 100 |
Responses
200A page of messages.
A page of messages.
| Name | Type | Description |
|---|---|---|
datarequired | array<IntegrationMessage> | |
metarequired | IntegrationPageMeta |
{
"data": [
{
"id": "5a6b7c8d-9e0f-4a1b-8c3d-4e5f6a7b8c9d",
"conversationId": "4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c",
"inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"type": "OUTGOING",
"contentType": "TEXT",
"status": "SENT",
"content": "Hello! Your order has shipped.",
"private": false,
"sender": {
"kind": "API_KEY",
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"name": "ERP integration"
},
"createdAt": "2026-01-15T13:45:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 42,
"totalPages": 3
}
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
| Name | Type | Description |
|---|---|---|
statusCoderequired | number | |
messagerequired | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorrequired | string |
Examples
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
404The resource does not exist, belongs to another account or is outside the inboxes of the key.
The resource does not exist, belongs to another account or is outside the inboxes of the key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl 'https://api.talkvend.com/v1/integrations/conversations/00000000-0000-0000-0000-000000000000/messages' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'/integrations/conversations/{conversationId}/messagesSend a text message or internal note
conversations:manageIdempotentSigned by the API key. Does not count as the first agent reply, ends an active bot session and reopens a resolved conversation. isPrivate: true creates an internal note that never reaches the contact (exempt from the 24 h window).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
conversationIdrequired | path | string · uuid | |
Idempotency-Keyoptional | header | string |
length 1–255 |
Request body (application/json)
| Name | Type | Description |
|---|---|---|
contentrequired | string | length 1–100000 |
isPrivateoptional | boolean | Internal note: kept in the conversation, never sent. Default: |
Responses
201The message created.
The message created.
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
conversationIdrequired | string · uuid | |
inboxIdrequired | string · uuid | |
typerequired | MessageType | Values: |
contentTyperequired | MessageContentType | Values: |
statusrequired | MessageStatus | Values: |
contentrequired | stringnullable | |
privaterequired | boolean | Internal note: visible to agents, never sent to the contact. |
senderrequired | IntegrationMessageSendernullable | Null for messages from the contact or from the system. |
createdAtrequired | string · date-time |
{
"id": "5a6b7c8d-9e0f-4a1b-8c3d-4e5f6a7b8c9d",
"conversationId": "4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c",
"inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"type": "OUTGOING",
"contentType": "TEXT",
"status": "SENT",
"content": "Hello! Your order has shipped.",
"private": false,
"sender": {
"kind": "API_KEY",
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"name": "ERP integration"
},
"createdAt": "2026-01-15T13:45:00.000Z"
}Response headers
- Idempotent-Replayed string
Present (
true) when this response replays the result of an earlier request with the sameIdempotency-Key.- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Examples
{
"code": "IDEMPOTENCY_KEY_INVALID",
"message": "IDEMPOTENCY_KEY_INVALID"
}{
"code": "MESSAGE_CONTENT_TOO_LONG",
"message": "MESSAGE_CONTENT_TOO_LONG"
}{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
404The resource does not exist, belongs to another account or is outside the inboxes of the key.
The resource does not exist, belongs to another account or is outside the inboxes of the key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
409The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
"message": "IDEMPOTENCY_REQUEST_IN_PROGRESS"
}{
"code": "META_OUTSIDE_WINDOW",
"message": "META_OUTSIDE_WINDOW"
}{
"code": "WHATSAPP_OUTSIDE_WINDOW",
"message": "WHATSAPP_OUTSIDE_WINDOW"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
422The request is well-formed but cannot be processed.
The request is well-formed but cannot be processed.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "IDEMPOTENCY_KEY_REUSED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl -X POST 'https://api.talkvend.com/v1/integrations/conversations/00000000-0000-0000-0000-000000000000/messages' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...' \
-H 'Idempotency-Key: order-12345-shipped' \
-H 'Content-Type: application/json' \
-d '{
"content": "Hello! Your order has shipped.",
"isPrivate": false
}'Messages
Labels
/integrations/labelsList labels
labels:readLabels of the account, used to classify conversations.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
pageoptional | query | integer | 1-based page number. Default: min 1 |
limitoptional | query | integer | Items per page (max 100). Default: min 1 · max 100 |
Responses
200A page of labels.
A page of labels.
| Name | Type | Description |
|---|---|---|
datarequired | array<IntegrationLabel> | |
metarequired | IntegrationPageMeta |
{
"data": [
{
"id": "6b7c8d9e-0f1a-4b2c-9d4e-5f6a7b8c9d0e",
"title": "billing",
"color": "#1F93FF",
"description": null
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 42,
"totalPages": 3
}
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
| Name | Type | Description |
|---|---|---|
statusCoderequired | number | |
messagerequired | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorrequired | string |
Examples
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl 'https://api.talkvend.com/v1/integrations/labels' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'Templates
/integrations/templatesList message templates
templates:readWhatsApp message templates of the account. Only APPROVED templates can be sent.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
statusoptional | query | TemplateStatus | Values: |
pageoptional | query | integer | 1-based page number. Default: min 1 |
limitoptional | query | integer | Items per page (max 100). Default: min 1 · max 100 |
Responses
200A page of templates.
A page of templates.
| Name | Type | Description |
|---|---|---|
datarequired | array<IntegrationTemplate> | |
metarequired | IntegrationPageMeta |
{
"data": [
{
"id": "7c8d9e0f-1a2b-4c3d-8e5f-6a7b8c9d0e1f",
"name": "order_shipped",
"language": "pt_BR",
"category": "UTILITY",
"status": "APPROVED",
"variables": [
{}
]
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 42,
"totalPages": 3
}
}Response headers
- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
| Name | Type | Description |
|---|---|---|
statusCoderequired | number | |
messagerequired | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorrequired | string |
Examples
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl 'https://api.talkvend.com/v1/integrations/templates' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'/integrations/templates/{templateId}/sendSend an approved WhatsApp template
conversations:manageIdempotentThe only way to reach a WhatsApp Cloud contact outside the 24 h window. Target exactly one of: conversationId; inboxId + contactId; or inboxId + contact (find-or-create by phone). parameters are keyed by variable name, e.g. { "client_name": "Maria" }.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
templateIdrequired | path | string · uuid | |
Idempotency-Keyoptional | header | string |
length 1–255 |
Request body (application/json)
| Name | Type | Description |
|---|---|---|
conversationIdoptional | string · uuid | Existing conversation (mode 1). |
inboxIdoptional | string · uuid | WhatsApp inbox to send from (modes 2 and 3). |
contactIdoptional | string · uuid | Existing contact (mode 2, with |
contactoptional | IntegrationTemplateContactInput | Contact to find or create (mode 3, with |
parametersoptional | map<string, string> | Template variable values keyed by variable name. |
Responses
201The template message created.
The template message created.
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
conversationIdrequired | string · uuid | |
inboxIdrequired | string · uuid | |
typerequired | MessageType | Values: |
contentTyperequired | MessageContentType | Values: |
statusrequired | MessageStatus | Values: |
contentrequired | stringnullable | |
privaterequired | boolean | Internal note: visible to agents, never sent to the contact. |
senderrequired | IntegrationMessageSendernullable | Null for messages from the contact or from the system. |
createdAtrequired | string · date-time |
{
"id": "5a6b7c8d-9e0f-4a1b-8c3d-4e5f6a7b8c9d",
"conversationId": "4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c",
"inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"type": "OUTGOING",
"contentType": "TEXT",
"status": "SENT",
"content": "Hello! Your order has shipped.",
"private": false,
"sender": {
"kind": "API_KEY",
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"name": "ERP integration"
},
"createdAt": "2026-01-15T13:45:00.000Z"
}Response headers
- Idempotent-Replayed string
Present (
true) when this response replays the result of an earlier request with the sameIdempotency-Key.- X-RateLimit-Limit integer
Requests allowed per minute for this key.
- X-RateLimit-Remaining integer
Requests left in the current window.
- X-RateLimit-Reset integer
Unix time (seconds) when the current window resets.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
400Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).
Examples
{
"code": "IDEMPOTENCY_KEY_INVALID",
"message": "IDEMPOTENCY_KEY_INVALID"
}{
"code": "TEMPLATE_CHANNEL_INVALID",
"message": "TEMPLATE_CHANNEL_INVALID"
}{
"code": "TEMPLATE_SEND_PARAMS_INVALID",
"message": "TEMPLATE_SEND_PARAMS_INVALID"
}{
"code": "TEMPLATE_SEND_TARGET_INVALID",
"message": "TEMPLATE_SEND_TARGET_INVALID"
}{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
401Missing, malformed, revoked or expired API key.
Missing, malformed, revoked or expired API key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
402The account has a pending payment; API access is blocked until it is settled.
The account has a pending payment; API access is blocked until it is settled.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
403The API key lacks the permission this operation requires (see x-vend-permission).
The API key lacks the permission this operation requires (see x-vend-permission).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
404The resource does not exist, belongs to another account or is outside the inboxes of the key.
The resource does not exist, belongs to another account or is outside the inboxes of the key.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "CONTACT_NOT_FOUND",
"message": "CONTACT_NOT_FOUND"
}{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}{
"code": "INBOX_NOT_FOUND",
"message": "INBOX_NOT_FOUND"
}{
"code": "TEMPLATE_NOT_FOUND",
"message": "TEMPLATE_NOT_FOUND"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
409The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
"message": "IDEMPOTENCY_REQUEST_IN_PROGRESS"
}{
"code": "INBOX_INACTIVE",
"message": "INBOX_INACTIVE"
}{
"code": "TEMPLATE_INACTIVE",
"message": "TEMPLATE_INACTIVE"
}{
"code": "TEMPLATE_NOT_APPROVED",
"message": "TEMPLATE_NOT_APPROVED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
422The request is well-formed but cannot be processed.
The request is well-formed but cannot be processed.
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "IDEMPOTENCY_KEY_REUSED"
}Response headers
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
429Rate limit exceeded (per key, per account or repeated authentication failures per IP).
Rate limit exceeded (per key, per account or repeated authentication failures per IP).
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Examples
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Response headers
- Retry-After integer
Seconds to wait before retrying.
- X-Request-Id string · uuid
Unique id of this request. Include it when contacting support.
curl -X POST 'https://api.talkvend.com/v1/integrations/templates/00000000-0000-0000-0000-000000000000/send' \
-H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...' \
-H 'Idempotency-Key: order-12345-shipped' \
-H 'Content-Type: application/json' \
-d '{
"conversationId": "4f5a6b7c-8d9e-4f0a-9b2c-3d4e5f6a7b8c",
"inboxId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"contactId": "3e4f5a6b-7c8d-4e9f-8a1b-2c3d4e5f6a7b",
"contact": {
"name": "Maria Silva",
"phoneNumber": "+55 11 90000-0000",
"email": "cliente@exemplo.com",
"identifier": "crm-000123",
"customAttributes": {
"plan": "silver"
}
},
"parameters": {
"client_name": "Maria"
}
}'Schemas
Schema
ChannelType
Values: "API""WHATSAPP_CLOUD""EVOLUTION""EMAIL""MESSENGER""INSTAGRAM""TWILIO_SMS"
Schema
ConversationStatus
Values: "OPEN""SNOOZED""RESOLVED""PENDING"
Schema
CustomAttributeModel
Values: "CONTACT""CONVERSATION"
Schema
CustomAttributeType
Values: "TEXT""NUMBER""DATE""LIST""CHECKBOX"
Schema
IntegrationAddLabelBody
| Name | Type | Description |
|---|---|---|
labelIdrequired | string · uuid |
Schema
IntegrationContact
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
namerequired | stringnullable | |
phoneNumberrequired | stringnullable | E.164 with |
emailrequired | string · emailnullable | |
identifierrequired | stringnullable | Your own identifier for this contact (e.g. CRM id). |
customAttributesrequired | object | Values keyed by custom attribute |
createdAtrequired | string · date-time | |
updatedAtrequired | string · date-time |
Schema
IntegrationConversation
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
displayIdrequired | number | Sequential number shown in the vend inbox. |
inboxIdrequired | string · uuid | |
contactIdrequired | string · uuid | |
statusrequired | ConversationStatus | Values: |
assigneeIdrequired | string · uuidnullable | |
snoozedUntilrequired | string · date-timenullable | |
resolvedAtrequired | string · date-timenullable | |
lastActivityAtrequired | string · date-time | |
subjectrequired | stringnullable | E-mail subject (e-mail inboxes only). |
labelsrequired | array<IntegrationConversationLabel> | |
createdAtrequired | string · date-time | |
updatedAtrequired | string · date-time |
Schema
IntegrationConversationContactInput
| Name | Type | Description |
|---|---|---|
namerequired | string | length 1–120 |
phoneNumberoptional | stringnullable | Phone in international format. length 1–32 |
emailoptional | string · emailnullable |
length 0–255 |
identifieroptional | stringnullable |
length 0–255 |
customAttributesoptional | objectnullable | Values keyed by custom attribute |
Schema
IntegrationConversationLabel
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
titlerequired | string |
Schema
IntegrationCreateContactDto
| Name | Type | Description |
|---|---|---|
namerequired | string | length 1–120 |
phoneNumberoptional | string | Phone in international format; stored as E.164. length 1–32 |
emailoptional | string · email | length 0–255 |
identifieroptional | string | Your own identifier for this contact (e.g. CRM id). length 0–255 |
customAttributesoptional | object | Values keyed by custom attribute |
Schema
IntegrationCreateConversationDto
| Name | Type | Description |
|---|---|---|
inboxIdrequired | string · uuid | |
contactIdoptional | string · uuid | Existing contact. Send exactly one of |
contactoptional | IntegrationConversationContactInput | Contact to find or create. Send exactly one of |
contentrequired | string | length 1–100000 |
subjectoptional | string | Required for e-mail inboxes; ignored by other channels. length 1–998 |
assigneeIdoptional | string · uuid | User to assign a new conversation to (active member of the inbox). Without it the conversation stays unassigned. |
Schema
IntegrationCreateConversationResult
| Name | Type | Description |
|---|---|---|
conversationrequired | IntegrationConversation | |
messagerequired | IntegrationMessage | |
createdrequired | boolean | False when an open conversation with this contact in this inbox was reused. |
Schema
IntegrationCustomAttribute
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
keyrequired | string | Key used in |
displayNamerequired | string | |
modelrequired | CustomAttributeModel | Values: |
typerequired | CustomAttributeType | Values: |
valuesrequired | array<string> | Allowed values (list attributes only). |
Schema
IntegrationError
| Name | Type | Description |
|---|---|---|
coderequired | string | Stable, machine-readable error code ( |
messagerequired | string | Same value as |
detailsoptional | object | Extra context, present only on a few codes. |
Schema
IntegrationInbox
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
namerequired | string | |
channelTyperequired | ChannelType | Values: |
activerequired | boolean |
Schema
IntegrationLabel
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
titlerequired | string | |
colorrequired | stringnullable | |
descriptionrequired | stringnullable |
Schema
IntegrationMe
| Name | Type | Description |
|---|---|---|
apiKeyrequired | IntegrationMeApiKey | |
accountrequired | IntegrationNamedRef | |
allInboxesrequired | boolean | True when the key is not restricted to specific inboxes (requires |
inboxesrequired | array<IntegrationNamedRef> | Inboxes the key is restricted to (empty when |
rateLimitrequired | IntegrationMeRateLimit |
Schema
IntegrationMeApiKey
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
namerequired | string | |
prefixrequired | string | Public part of the key (safe to log). |
permissionsrequired | array<string> |
Schema
IntegrationMeRateLimit
| Name | Type | Description |
|---|---|---|
perMinuterequired | number | Requests per minute for this key. |
accountPerMinuterequired | number | Requests per minute shared by every key of the account. |
Schema
IntegrationMessage
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
conversationIdrequired | string · uuid | |
inboxIdrequired | string · uuid | |
typerequired | MessageType | Values: |
contentTyperequired | MessageContentType | Values: |
statusrequired | MessageStatus | Values: |
contentrequired | stringnullable | |
privaterequired | boolean | Internal note: visible to agents, never sent to the contact. |
senderrequired | IntegrationMessageSendernullable | Null for messages from the contact or from the system. |
createdAtrequired | string · date-time |
Schema
IntegrationMessageSender
| Name | Type | Description |
|---|---|---|
kindrequired | string | A vend user (agent) or an API key. Values: |
idrequired | string · uuid | |
namerequired | stringnullable |
Schema
IntegrationNamedRef
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
namerequired | string |
Schema
IntegrationPageMeta
| Name | Type | Description |
|---|---|---|
pagerequired | number | min 1 |
limitrequired | number | min 1 · max 100 |
totalrequired | number | min 0 |
totalPagesrequired | number | min 0 |
Schema
IntegrationSendMessageDto
| Name | Type | Description |
|---|---|---|
contentrequired | string | length 1–100000 |
isPrivateoptional | boolean | Internal note: kept in the conversation, never sent. Default: |
Schema
IntegrationSendTemplateDto
| Name | Type | Description |
|---|---|---|
conversationIdoptional | string · uuid | Existing conversation (mode 1). |
inboxIdoptional | string · uuid | WhatsApp inbox to send from (modes 2 and 3). |
contactIdoptional | string · uuid | Existing contact (mode 2, with |
contactoptional | IntegrationTemplateContactInput | Contact to find or create (mode 3, with |
parametersoptional | map<string, string> | Template variable values keyed by variable name. |
Schema
IntegrationTemplate
| Name | Type | Description |
|---|---|---|
idrequired | string · uuid | |
namerequired | string | |
languagerequired | string | Meta language code (e.g. |
categoryrequired | TemplateCategorynullable | Values: |
statusrequired | TemplateStatusnullable | Values: |
variablesrequired | array<object> | Template variables. Send values by variable name in |
Schema
IntegrationTemplateContactInput
| Name | Type | Description |
|---|---|---|
namerequired | string | length 1–120 |
phoneNumberrequired | string | Phone in international format. length 1–32 |
emailoptional | string · emailnullable |
length 0–255 |
identifieroptional | stringnullable |
length 0–255 |
customAttributesoptional | objectnullable | Values keyed by custom attribute |
Schema
IntegrationUpdateContactDto
| Name | Type | Description |
|---|---|---|
nameoptional | string | length 1–120 |
phoneNumberoptional | string | Phone in international format; stored as E.164. length 1–32 |
emailoptional | string · emailnullable |
length 0–255 |
identifieroptional | stringnullable | Your own identifier for this contact; length 0–255 |
customAttributesoptional | object | Values keyed by custom attribute |
Schema
IntegrationUpdateConversationDto
| Name | Type | Description |
|---|---|---|
statusoptional | ConversationStatus | Values: |
assigneeIdoptional | string · uuidnullable | User to assign (must be an active member of the inbox); |
snoozedUntiloptional | string · date-timenullable | Snooze until this moment; |
Schema
IntegrationValidationError
| Name | Type | Description |
|---|---|---|
statusCoderequired | number | |
messagerequired | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorrequired | string |
Schema
MessageContentType
Values: "TEXT""IMAGE""AUDIO""VIDEO""FILE"
Schema
MessageStatus
Values: "SENT""DELIVERED""READ""FAILED"
Schema
MessageType
Values: "INCOMING""OUTGOING""ACTIVITY""TEMPLATE"
Schema
TemplateCategory
Values: "MARKETING""UTILITY""AUTHENTICATION"
Schema
TemplateStatus
Values: "PENDING""APPROVED""REJECTED""PAUSED""DISABLED"