Referência da API
vend Integration API
v1.0.0Base URL: https://api.talkvend.com/v1
As descrições abaixo vêm da especificação da API e estão em inglês.
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.
Respostas
200The API key used in this request.
The API key used in this request.
| Nome | Tipo | Descrição |
|---|---|---|
apiKeyobrigatório | IntegrationMeApiKey | |
accountobrigatório | IntegrationNamedRef | |
allInboxesobrigatório | boolean | True when the key is not restricted to specific inboxes (requires |
inboxesobrigatório | array<IntegrationNamedRef> | Inboxes the key is restricted to (empty when |
rateLimitobrigatório | 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
}
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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.
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
pageopcional | query | integer | 1-based page number. Padrão: min 1 |
limitopcional | query | integer | Items per page (max 100). Padrão: min 1 · max 100 |
Respostas
200A page of inboxes.
A page of inboxes.
| Nome | Tipo | Descrição |
|---|---|---|
dataobrigatório | array<IntegrationInbox> | |
metaobrigatório | 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
}
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
statusCodeobrigatório | number | |
messageobrigatório | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorobrigatório | string |
Exemplos
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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.
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
searchopcional | query | string | Substring of the name, phone number or e-mail. length 0–120 |
pageopcional | query | integer | 1-based page number. Padrão: min 1 |
limitopcional | query | integer | Items per page (max 100). Padrão: min 1 · max 100 |
Respostas
200A page of contacts.
A page of contacts.
| Nome | Tipo | Descrição |
|---|---|---|
dataobrigatório | array<IntegrationContact> | |
metaobrigatório | 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
}
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
statusCodeobrigatório | number | |
messageobrigatório | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorobrigatório | string |
Exemplos
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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.
Corpo da requisição (application/json)
| Nome | Tipo | Descrição |
|---|---|---|
nameobrigatório | string | length 1–120 |
phoneNumberopcional | string | Phone in international format; stored as E.164. length 1–32 |
emailopcional | string · email | length 0–255 |
identifieropcional | string | Your own identifier for this contact (e.g. CRM id). length 0–255 |
customAttributesopcional | object | Values keyed by custom attribute |
Respostas
201The created contact.
The created contact.
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
nameobrigatório | stringpode ser null | |
phoneNumberobrigatório | stringpode ser null | E.164 with |
emailobrigatório | string · emailpode ser null | |
identifierobrigatório | stringpode ser null | Your own identifier for this contact (e.g. CRM id). |
customAttributesobrigatório | object | Values keyed by custom attribute |
createdAtobrigatório | string · date-time | |
updatedAtobrigatório | 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"
}Headers da resposta
- 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).
Exemplos
{
"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
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "CONTACT_PHONE_EXISTS",
"message": "CONTACT_PHONE_EXISTS"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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:readParâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
contactIdobrigatório | path | string · uuid |
Respostas
200The contact.
The contact.
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
nameobrigatório | stringpode ser null | |
phoneNumberobrigatório | stringpode ser null | E.164 with |
emailobrigatório | string · emailpode ser null | |
identifierobrigatório | stringpode ser null | Your own identifier for this contact (e.g. CRM id). |
customAttributesobrigatório | object | Values keyed by custom attribute |
createdAtobrigatório | string · date-time | |
updatedAtobrigatório | 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"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
statusCodeobrigatório | number | |
messageobrigatório | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorobrigatório | string |
Exemplos
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "CONTACT_NOT_FOUND",
"message": "CONTACT_NOT_FOUND"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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.
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
contactIdobrigatório | path | string · uuid |
Corpo da requisição (application/json)
| Nome | Tipo | Descrição |
|---|---|---|
nameopcional | string | length 1–120 |
phoneNumberopcional | string | Phone in international format; stored as E.164. length 1–32 |
emailopcional | string · emailpode ser null |
length 0–255 |
identifieropcional | stringpode ser null | Your own identifier for this contact; length 0–255 |
customAttributesopcional | object | Values keyed by custom attribute |
Respostas
200The updated contact.
The updated contact.
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
nameobrigatório | stringpode ser null | |
phoneNumberobrigatório | stringpode ser null | E.164 with |
emailobrigatório | string · emailpode ser null | |
identifierobrigatório | stringpode ser null | Your own identifier for this contact (e.g. CRM id). |
customAttributesobrigatório | object | Values keyed by custom attribute |
createdAtobrigatório | string · date-time | |
updatedAtobrigatório | 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"
}Headers da resposta
- 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).
Exemplos
{
"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
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "CONTACT_NOT_FOUND",
"message": "CONTACT_NOT_FOUND"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "CONTACT_PHONE_EXISTS",
"message": "CONTACT_PHONE_EXISTS"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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.
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
modelopcional | query | CustomAttributeModel | Valores: |
pageopcional | query | integer | 1-based page number. Padrão: min 1 |
limitopcional | query | integer | Items per page (max 100). Padrão: min 1 · max 100 |
Respostas
200A page of custom attribute definitions.
A page of custom attribute definitions.
| Nome | Tipo | Descrição |
|---|---|---|
dataobrigatório | array<IntegrationCustomAttribute> | |
metaobrigatório | 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
}
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
statusCodeobrigatório | number | |
messageobrigatório | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorobrigatório | string |
Exemplos
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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.
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
statusopcional | query | ConversationStatus | Valores: |
inboxIdopcional | query | string · uuid | |
contactIdopcional | query | string · uuid | |
assigneeIdopcional | query | string · uuid | |
labelIdopcional | query | string · uuid | |
pageopcional | query | integer | 1-based page number. Padrão: min 1 |
limitopcional | query | integer | Items per page (max 100). Padrão: min 1 · max 100 |
Respostas
200A page of conversations.
A page of conversations.
| Nome | Tipo | Descrição |
|---|---|---|
dataobrigatório | array<IntegrationConversation> | |
metaobrigatório | 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
}
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
statusCodeobrigatório | number | |
messageobrigatório | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorobrigatório | string |
Exemplos
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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:manageIdempotenteSends 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.
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
Idempotency-Keyopcional | header | string |
length 1–255 |
Corpo da requisição (application/json)
IntegrationCreateConversationDto
| Nome | Tipo | Descrição |
|---|---|---|
inboxIdobrigatório | string · uuid | |
contactIdopcional | string · uuid | Existing contact. Send exactly one of |
contactopcional | IntegrationConversationContactInput | Contact to find or create. Send exactly one of |
contentobrigatório | string | length 1–100000 |
subjectopcional | string | Required for e-mail inboxes; ignored by other channels. length 1–998 |
assigneeIdopcional | string · uuid | User to assign a new conversation to (active member of the inbox). Without it the conversation stays unassigned. |
Respostas
201The conversation and the message sent.
The conversation and the message sent.
IntegrationCreateConversationResult
| Nome | Tipo | Descrição |
|---|---|---|
conversationobrigatório | IntegrationConversation | |
messageobrigatório | IntegrationMessage | |
createdobrigatório | 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
}Headers da resposta
- 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).
Exemplos
{
"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
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "CONTACT_NOT_FOUND",
"message": "CONTACT_NOT_FOUND"
}{
"code": "INBOX_NOT_FOUND",
"message": "INBOX_NOT_FOUND"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"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"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "IDEMPOTENCY_KEY_REUSED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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:readParâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
conversationIdobrigatório | path | string · uuid |
Respostas
200The conversation.
The conversation.
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
displayIdobrigatório | number | Sequential number shown in the vend inbox. |
inboxIdobrigatório | string · uuid | |
contactIdobrigatório | string · uuid | |
statusobrigatório | ConversationStatus | Valores: |
assigneeIdobrigatório | string · uuidpode ser null | |
snoozedUntilobrigatório | string · date-timepode ser null | |
resolvedAtobrigatório | string · date-timepode ser null | |
lastActivityAtobrigatório | string · date-time | |
subjectobrigatório | stringpode ser null | E-mail subject (e-mail inboxes only). |
labelsobrigatório | array<IntegrationConversationLabel> | |
createdAtobrigatório | string · date-time | |
updatedAtobrigatório | 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"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
statusCodeobrigatório | number | |
messageobrigatório | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorobrigatório | string |
Exemplos
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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.
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
conversationIdobrigatório | path | string · uuid |
Corpo da requisição (application/json)
IntegrationUpdateConversationDto
| Nome | Tipo | Descrição |
|---|---|---|
statusopcional | ConversationStatus | Valores: |
assigneeIdopcional | string · uuidpode ser null | User to assign (must be an active member of the inbox); |
snoozedUntilopcional | string · date-timepode ser null | Snooze until this moment; |
Respostas
200The updated conversation.
The updated conversation.
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
displayIdobrigatório | number | Sequential number shown in the vend inbox. |
inboxIdobrigatório | string · uuid | |
contactIdobrigatório | string · uuid | |
statusobrigatório | ConversationStatus | Valores: |
assigneeIdobrigatório | string · uuidpode ser null | |
snoozedUntilobrigatório | string · date-timepode ser null | |
resolvedAtobrigatório | string · date-timepode ser null | |
lastActivityAtobrigatório | string · date-time | |
subjectobrigatório | stringpode ser null | E-mail subject (e-mail inboxes only). |
labelsobrigatório | array<IntegrationConversationLabel> | |
createdAtobrigatório | string · date-time | |
updatedAtobrigatório | 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"
}Headers da resposta
- 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).
Exemplos
{
"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
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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:manageParâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
conversationIdobrigatório | path | string · uuid |
Corpo da requisição (application/json)
| Nome | Tipo | Descrição |
|---|---|---|
labelIdobrigatório | string · uuid |
Respostas
200The conversation with its labels.
The conversation with its labels.
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
displayIdobrigatório | number | Sequential number shown in the vend inbox. |
inboxIdobrigatório | string · uuid | |
contactIdobrigatório | string · uuid | |
statusobrigatório | ConversationStatus | Valores: |
assigneeIdobrigatório | string · uuidpode ser null | |
snoozedUntilobrigatório | string · date-timepode ser null | |
resolvedAtobrigatório | string · date-timepode ser null | |
lastActivityAtobrigatório | string · date-time | |
subjectobrigatório | stringpode ser null | E-mail subject (e-mail inboxes only). |
labelsobrigatório | array<IntegrationConversationLabel> | |
createdAtobrigatório | string · date-time | |
updatedAtobrigatório | 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"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
statusCodeobrigatório | number | |
messageobrigatório | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorobrigatório | string |
Exemplos
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}{
"code": "LABEL_NOT_FOUND",
"message": "LABEL_NOT_FOUND"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "LABEL_CONVERSATION_ALREADY_EXISTS",
"message": "LABEL_CONVERSATION_ALREADY_EXISTS"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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:manageParâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
conversationIdobrigatório | path | string · uuid | |
labelIdobrigatório | path | string · uuid |
Respostas
200The conversation with its labels.
The conversation with its labels.
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
displayIdobrigatório | number | Sequential number shown in the vend inbox. |
inboxIdobrigatório | string · uuid | |
contactIdobrigatório | string · uuid | |
statusobrigatório | ConversationStatus | Valores: |
assigneeIdobrigatório | string · uuidpode ser null | |
snoozedUntilobrigatório | string · date-timepode ser null | |
resolvedAtobrigatório | string · date-timepode ser null | |
lastActivityAtobrigatório | string · date-time | |
subjectobrigatório | stringpode ser null | E-mail subject (e-mail inboxes only). |
labelsobrigatório | array<IntegrationConversationLabel> | |
createdAtobrigatório | string · date-time | |
updatedAtobrigatório | 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"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
statusCodeobrigatório | number | |
messageobrigatório | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorobrigatório | string |
Exemplos
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}{
"code": "LABEL_CONVERSATION_NOT_FOUND",
"message": "LABEL_CONVERSATION_NOT_FOUND"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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.
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
conversationIdobrigatório | path | string · uuid | |
pageopcional | query | integer | 1-based page number. Padrão: min 1 |
limitopcional | query | integer | Items per page (max 100). Padrão: min 1 · max 100 |
Respostas
200A page of messages.
A page of messages.
| Nome | Tipo | Descrição |
|---|---|---|
dataobrigatório | array<IntegrationMessage> | |
metaobrigatório | 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
}
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
statusCodeobrigatório | number | |
messageobrigatório | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorobrigatório | string |
Exemplos
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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:manageIdempotenteSigned 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).
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
conversationIdobrigatório | path | string · uuid | |
Idempotency-Keyopcional | header | string |
length 1–255 |
Corpo da requisição (application/json)
| Nome | Tipo | Descrição |
|---|---|---|
contentobrigatório | string | length 1–100000 |
isPrivateopcional | boolean | Internal note: kept in the conversation, never sent. Padrão: |
Respostas
201The message created.
The message created.
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
conversationIdobrigatório | string · uuid | |
inboxIdobrigatório | string · uuid | |
typeobrigatório | MessageType | Valores: |
contentTypeobrigatório | MessageContentType | Valores: |
statusobrigatório | MessageStatus | Valores: |
contentobrigatório | stringpode ser null | |
privateobrigatório | boolean | Internal note: visible to agents, never sent to the contact. |
senderobrigatório | IntegrationMessageSenderpode ser null | Null for messages from the contact or from the system. |
createdAtobrigatório | 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"
}Headers da resposta
- 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).
Exemplos
{
"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
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "CONVERSATION_NOT_FOUND",
"message": "CONVERSATION_NOT_FOUND"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"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"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "IDEMPOTENCY_KEY_REUSED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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.
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
pageopcional | query | integer | 1-based page number. Padrão: min 1 |
limitopcional | query | integer | Items per page (max 100). Padrão: min 1 · max 100 |
Respostas
200A page of labels.
A page of labels.
| Nome | Tipo | Descrição |
|---|---|---|
dataobrigatório | array<IntegrationLabel> | |
metaobrigatório | IntegrationPageMeta |
{
"data": [
{
"id": "6b7c8d9e-0f1a-4b2c-9d4e-5f6a7b8c9d0e",
"title": "billing",
"color": "#1F93FF",
"description": null
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 42,
"totalPages": 3
}
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
statusCodeobrigatório | number | |
messageobrigatório | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorobrigatório | string |
Exemplos
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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.
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
statusopcional | query | TemplateStatus | Valores: |
pageopcional | query | integer | 1-based page number. Padrão: min 1 |
limitopcional | query | integer | Items per page (max 100). Padrão: min 1 · max 100 |
Respostas
200A page of templates.
A page of templates.
| Nome | Tipo | Descrição |
|---|---|---|
dataobrigatório | array<IntegrationTemplate> | |
metaobrigatório | 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
}
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
statusCodeobrigatório | number | |
messageobrigatório | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorobrigatório | string |
Exemplos
{
"error": "Bad Request",
"message": [
"limit must not be greater than 100"
],
"statusCode": 400
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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:manageIdempotenteThe 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" }.
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
templateIdobrigatório | path | string · uuid | |
Idempotency-Keyopcional | header | string |
length 1–255 |
Corpo da requisição (application/json)
| Nome | Tipo | Descrição |
|---|---|---|
conversationIdopcional | string · uuid | Existing conversation (mode 1). |
inboxIdopcional | string · uuid | WhatsApp inbox to send from (modes 2 and 3). |
contactIdopcional | string · uuid | Existing contact (mode 2, with |
contactopcional | IntegrationTemplateContactInput | Contact to find or create (mode 3, with |
parametersopcional | map<string, string> | Template variable values keyed by variable name. |
Respostas
201The template message created.
The template message created.
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
conversationIdobrigatório | string · uuid | |
inboxIdobrigatório | string · uuid | |
typeobrigatório | MessageType | Valores: |
contentTypeobrigatório | MessageContentType | Valores: |
statusobrigatório | MessageStatus | Valores: |
contentobrigatório | stringpode ser null | |
privateobrigatório | boolean | Internal note: visible to agents, never sent to the contact. |
senderobrigatório | IntegrationMessageSenderpode ser null | Null for messages from the contact or from the system. |
createdAtobrigatório | 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"
}Headers da resposta
- 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).
Exemplos
{
"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
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INVALID",
"message": "API_KEY_INVALID"
}{
"code": "API_KEY_MISSING",
"message": "API_KEY_MISSING"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "ACCOUNT_PAYMENT_REQUIRED",
"message": "ACCOUNT_PAYMENT_REQUIRED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_INSUFFICIENT_PERMISSION",
"message": "API_KEY_INSUFFICIENT_PERMISSION"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"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"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"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"
}Headers da resposta
- 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.
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "IDEMPOTENCY_KEY_REUSED"
}Headers da resposta
- 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).
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Exemplos
{
"code": "API_KEY_RATE_LIMITED",
"message": "API_KEY_RATE_LIMITED"
}Headers da resposta
- 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
Valores: "API""WHATSAPP_CLOUD""EVOLUTION""EMAIL""MESSENGER""INSTAGRAM""TWILIO_SMS"
Schema
ConversationStatus
Valores: "OPEN""SNOOZED""RESOLVED""PENDING"
Schema
CustomAttributeModel
Valores: "CONTACT""CONVERSATION"
Schema
CustomAttributeType
Valores: "TEXT""NUMBER""DATE""LIST""CHECKBOX"
Schema
IntegrationAddLabelBody
| Nome | Tipo | Descrição |
|---|---|---|
labelIdobrigatório | string · uuid |
Schema
IntegrationContact
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
nameobrigatório | stringpode ser null | |
phoneNumberobrigatório | stringpode ser null | E.164 with |
emailobrigatório | string · emailpode ser null | |
identifierobrigatório | stringpode ser null | Your own identifier for this contact (e.g. CRM id). |
customAttributesobrigatório | object | Values keyed by custom attribute |
createdAtobrigatório | string · date-time | |
updatedAtobrigatório | string · date-time |
Schema
IntegrationConversation
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
displayIdobrigatório | number | Sequential number shown in the vend inbox. |
inboxIdobrigatório | string · uuid | |
contactIdobrigatório | string · uuid | |
statusobrigatório | ConversationStatus | Valores: |
assigneeIdobrigatório | string · uuidpode ser null | |
snoozedUntilobrigatório | string · date-timepode ser null | |
resolvedAtobrigatório | string · date-timepode ser null | |
lastActivityAtobrigatório | string · date-time | |
subjectobrigatório | stringpode ser null | E-mail subject (e-mail inboxes only). |
labelsobrigatório | array<IntegrationConversationLabel> | |
createdAtobrigatório | string · date-time | |
updatedAtobrigatório | string · date-time |
Schema
IntegrationConversationContactInput
| Nome | Tipo | Descrição |
|---|---|---|
nameobrigatório | string | length 1–120 |
phoneNumberopcional | stringpode ser null | Phone in international format. length 1–32 |
emailopcional | string · emailpode ser null |
length 0–255 |
identifieropcional | stringpode ser null |
length 0–255 |
customAttributesopcional | objectpode ser null | Values keyed by custom attribute |
Schema
IntegrationConversationLabel
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
titleobrigatório | string |
Schema
IntegrationCreateContactDto
| Nome | Tipo | Descrição |
|---|---|---|
nameobrigatório | string | length 1–120 |
phoneNumberopcional | string | Phone in international format; stored as E.164. length 1–32 |
emailopcional | string · email | length 0–255 |
identifieropcional | string | Your own identifier for this contact (e.g. CRM id). length 0–255 |
customAttributesopcional | object | Values keyed by custom attribute |
Schema
IntegrationCreateConversationDto
| Nome | Tipo | Descrição |
|---|---|---|
inboxIdobrigatório | string · uuid | |
contactIdopcional | string · uuid | Existing contact. Send exactly one of |
contactopcional | IntegrationConversationContactInput | Contact to find or create. Send exactly one of |
contentobrigatório | string | length 1–100000 |
subjectopcional | string | Required for e-mail inboxes; ignored by other channels. length 1–998 |
assigneeIdopcional | string · uuid | User to assign a new conversation to (active member of the inbox). Without it the conversation stays unassigned. |
Schema
IntegrationCreateConversationResult
| Nome | Tipo | Descrição |
|---|---|---|
conversationobrigatório | IntegrationConversation | |
messageobrigatório | IntegrationMessage | |
createdobrigatório | boolean | False when an open conversation with this contact in this inbox was reused. |
Schema
IntegrationCustomAttribute
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
keyobrigatório | string | Key used in |
displayNameobrigatório | string | |
modelobrigatório | CustomAttributeModel | Valores: |
typeobrigatório | CustomAttributeType | Valores: |
valuesobrigatório | array<string> | Allowed values (list attributes only). |
Schema
IntegrationError
| Nome | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Stable, machine-readable error code ( |
messageobrigatório | string | Same value as |
detailsopcional | object | Extra context, present only on a few codes. |
Schema
IntegrationInbox
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
nameobrigatório | string | |
channelTypeobrigatório | ChannelType | Valores: |
activeobrigatório | boolean |
Schema
IntegrationLabel
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
titleobrigatório | string | |
colorobrigatório | stringpode ser null | |
descriptionobrigatório | stringpode ser null |
Schema
IntegrationMe
| Nome | Tipo | Descrição |
|---|---|---|
apiKeyobrigatório | IntegrationMeApiKey | |
accountobrigatório | IntegrationNamedRef | |
allInboxesobrigatório | boolean | True when the key is not restricted to specific inboxes (requires |
inboxesobrigatório | array<IntegrationNamedRef> | Inboxes the key is restricted to (empty when |
rateLimitobrigatório | IntegrationMeRateLimit |
Schema
IntegrationMeApiKey
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
nameobrigatório | string | |
prefixobrigatório | string | Public part of the key (safe to log). |
permissionsobrigatório | array<string> |
Schema
IntegrationMeRateLimit
| Nome | Tipo | Descrição |
|---|---|---|
perMinuteobrigatório | number | Requests per minute for this key. |
accountPerMinuteobrigatório | number | Requests per minute shared by every key of the account. |
Schema
IntegrationMessage
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
conversationIdobrigatório | string · uuid | |
inboxIdobrigatório | string · uuid | |
typeobrigatório | MessageType | Valores: |
contentTypeobrigatório | MessageContentType | Valores: |
statusobrigatório | MessageStatus | Valores: |
contentobrigatório | stringpode ser null | |
privateobrigatório | boolean | Internal note: visible to agents, never sent to the contact. |
senderobrigatório | IntegrationMessageSenderpode ser null | Null for messages from the contact or from the system. |
createdAtobrigatório | string · date-time |
Schema
IntegrationMessageSender
| Nome | Tipo | Descrição |
|---|---|---|
kindobrigatório | string | A vend user (agent) or an API key. Valores: |
idobrigatório | string · uuid | |
nameobrigatório | stringpode ser null |
Schema
IntegrationNamedRef
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
nameobrigatório | string |
Schema
IntegrationPageMeta
| Nome | Tipo | Descrição |
|---|---|---|
pageobrigatório | number | min 1 |
limitobrigatório | number | min 1 · max 100 |
totalobrigatório | number | min 0 |
totalPagesobrigatório | number | min 0 |
Schema
IntegrationSendMessageDto
| Nome | Tipo | Descrição |
|---|---|---|
contentobrigatório | string | length 1–100000 |
isPrivateopcional | boolean | Internal note: kept in the conversation, never sent. Padrão: |
Schema
IntegrationSendTemplateDto
| Nome | Tipo | Descrição |
|---|---|---|
conversationIdopcional | string · uuid | Existing conversation (mode 1). |
inboxIdopcional | string · uuid | WhatsApp inbox to send from (modes 2 and 3). |
contactIdopcional | string · uuid | Existing contact (mode 2, with |
contactopcional | IntegrationTemplateContactInput | Contact to find or create (mode 3, with |
parametersopcional | map<string, string> | Template variable values keyed by variable name. |
Schema
IntegrationTemplate
| Nome | Tipo | Descrição |
|---|---|---|
idobrigatório | string · uuid | |
nameobrigatório | string | |
languageobrigatório | string | Meta language code (e.g. |
categoryobrigatório | TemplateCategorypode ser null | Valores: |
statusobrigatório | TemplateStatuspode ser null | Valores: |
variablesobrigatório | array<object> | Template variables. Send values by variable name in |
Schema
IntegrationTemplateContactInput
| Nome | Tipo | Descrição |
|---|---|---|
nameobrigatório | string | length 1–120 |
phoneNumberobrigatório | string | Phone in international format. length 1–32 |
emailopcional | string · emailpode ser null |
length 0–255 |
identifieropcional | stringpode ser null |
length 0–255 |
customAttributesopcional | objectpode ser null | Values keyed by custom attribute |
Schema
IntegrationUpdateContactDto
| Nome | Tipo | Descrição |
|---|---|---|
nameopcional | string | length 1–120 |
phoneNumberopcional | string | Phone in international format; stored as E.164. length 1–32 |
emailopcional | string · emailpode ser null |
length 0–255 |
identifieropcional | stringpode ser null | Your own identifier for this contact; length 0–255 |
customAttributesopcional | object | Values keyed by custom attribute |
Schema
IntegrationUpdateConversationDto
| Nome | Tipo | Descrição |
|---|---|---|
statusopcional | ConversationStatus | Valores: |
assigneeIdopcional | string · uuidpode ser null | User to assign (must be an active member of the inbox); |
snoozedUntilopcional | string · date-timepode ser null | Snooze until this moment; |
Schema
IntegrationValidationError
| Nome | Tipo | Descrição |
|---|---|---|
statusCodeobrigatório | number | |
messageobrigatório | array<string> | string | One entry per rejected body/query field, or a single string for an invalid path parameter. |
errorobrigatório | string |
Schema
MessageContentType
Valores: "TEXT""IMAGE""AUDIO""VIDEO""FILE"
Schema
MessageStatus
Valores: "SENT""DELIVERED""READ""FAILED"
Schema
MessageType
Valores: "INCOMING""OUTGOING""ACTIVITY""TEMPLATE"
Schema
TemplateCategory
Valores: "MARKETING""UTILITY""AUTHENTICATION"
Schema
TemplateStatus
Valores: "PENDING""APPROVED""REJECTED""PAUSED""DISABLED"