Pular para o conteúdo
talkvend

Desenvolvedores

Referência da API

Todos os endpoints, parâmetros e respostas, gerados da especificação OpenAPI em produção.

vend Integration API

v1.0.0

Base 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

get/integrations/me

Inspect the current API key

Permissão:qualquer chave válida

Returns the key, its account, permissions, inbox restriction and rate limits. Requires no permission: use it to test a key.

Respostas

200

The API key used in this request.

IntegrationMe

NomeTipoDescrição
apiKeyobrigatórioIntegrationMeApiKey
accountobrigatórioIntegrationNamedRef
allInboxesobrigatórioboolean

True when the key is not restricted to specific inboxes (requires conversations:read-all).

inboxesobrigatórioarray<IntegrationNamedRef>

Inboxes the key is restricted to (empty when allInboxes).

rateLimitobrigatórioIntegrationMeRateLimit
Exemplo
{
  "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
  }
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
curl 'https://api.talkvend.com/v1/integrations/me' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'

Inboxes

get/integrations/inboxes

List inboxes

Permissão:inboxes:read

Inboxes the key can use: only the ones it is restricted to, if any.

Parâmetros

NomeLocalTipoDescrição
pageopcionalqueryinteger

1-based page number.

Padrão: 1

min 1

limitopcionalqueryinteger

Items per page (max 100).

Padrão: 20

min 1 · max 100

Respostas

200

A page of inboxes.

NomeTipoDescrição
dataobrigatórioarray<IntegrationInbox>
metaobrigatórioIntegrationPageMeta
Exemplo
{
  "data": [
    {
      "id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
      "name": "Support WhatsApp",
      "channelType": "WHATSAPP_CLOUD",
      "active": true
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

IntegrationValidationError

NomeTipoDescrição
statusCodeobrigatórionumber
messageobrigatórioarray<string> | string

One entry per rejected body/query field, or a single string for an invalid path parameter.

errorobrigatóriostring

Exemplos

Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
curl 'https://api.talkvend.com/v1/integrations/inboxes' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'

Contacts

get/integrations/contacts

List contacts

Permissão:contacts:read

Contacts of the whole account (not restricted by the inboxes of the key), newest first.

Parâmetros

NomeLocalTipoDescrição
searchopcionalquerystring

Substring of the name, phone number or e-mail.

length 0–120

pageopcionalqueryinteger

1-based page number.

Padrão: 1

min 1

limitopcionalqueryinteger

Items per page (max 100).

Padrão: 20

min 1 · max 100

Respostas

200

A page of contacts.

NomeTipoDescrição
dataobrigatórioarray<IntegrationContact>
metaobrigatórioIntegrationPageMeta
Exemplo
{
  "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
  }
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

IntegrationValidationError

NomeTipoDescrição
statusCodeobrigatórionumber
messageobrigatórioarray<string> | string

One entry per rejected body/query field, or a single string for an invalid path parameter.

errorobrigatóriostring

Exemplos

Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
curl 'https://api.talkvend.com/v1/integrations/contacts' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'
post/integrations/contacts

Create a contact

Permissão:contacts:manage

Phone numbers are normalized to E.164. customAttributes keys must exist in GET /integrations/custom-attributes.

Corpo da requisição (application/json)

IntegrationCreateContactDto

NomeTipoDescrição
nameobrigatóriostring

length 1–120

phoneNumberopcionalstring

Phone in international format; stored as E.164.

length 1–32

emailopcionalstring · email

length 0–255

identifieropcionalstring

Your own identifier for this contact (e.g. CRM id).

length 0–255

customAttributesopcionalobject

Values keyed by custom attribute key.

Respostas

201

The created contact.

IntegrationContact

NomeTipoDescrição
idobrigatóriostring · uuid
nameobrigatóriostringpode ser null
phoneNumberobrigatóriostringpode ser null

E.164 with +, or null.

emailobrigatóriostring · emailpode ser null
identifierobrigatóriostringpode ser null

Your own identifier for this contact (e.g. CRM id).

customAttributesobrigatórioobject

Values keyed by custom attribute key (see GET /integrations/custom-attributes).

createdAtobrigatóriostring · date-time
updatedAtobrigatóriostring · date-time
Exemplo
{
  "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"
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

Exemplos

CONTACT_ATTRIBUTE_INVALID
{
  "code": "CONTACT_ATTRIBUTE_INVALID",
  "message": "CONTACT_ATTRIBUTE_INVALID"
}
CONTACT_ATTRIBUTE_UNKNOWN
{
  "code": "CONTACT_ATTRIBUTE_UNKNOWN",
  "message": "CONTACT_ATTRIBUTE_UNKNOWN"
}
CONTACT_PHONE_INVALID
{
  "code": "CONTACT_PHONE_INVALID",
  "message": "CONTACT_PHONE_INVALID"
}
Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

409

The request conflicts with the current state of the resource.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

CONTACT_PHONE_EXISTS
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
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"
  }
}'

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

get/integrations/contacts/{contactId}

Get a contact

Permissão:contacts:read

Parâmetros

NomeLocalTipoDescrição
contactIdobrigatóriopathstring · uuid

Respostas

200

The contact.

IntegrationContact

NomeTipoDescrição
idobrigatóriostring · uuid
nameobrigatóriostringpode ser null
phoneNumberobrigatóriostringpode ser null

E.164 with +, or null.

emailobrigatóriostring · emailpode ser null
identifierobrigatóriostringpode ser null

Your own identifier for this contact (e.g. CRM id).

customAttributesobrigatórioobject

Values keyed by custom attribute key (see GET /integrations/custom-attributes).

createdAtobrigatóriostring · date-time
updatedAtobrigatóriostring · date-time
Exemplo
{
  "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"
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

IntegrationValidationError

NomeTipoDescrição
statusCodeobrigatórionumber
messageobrigatórioarray<string> | string

One entry per rejected body/query field, or a single string for an invalid path parameter.

errorobrigatóriostring

Exemplos

Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

404

The resource does not exist, belongs to another account or is outside the inboxes of the key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

CONTACT_NOT_FOUND
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
curl 'https://api.talkvend.com/v1/integrations/contacts/00000000-0000-0000-0000-000000000000' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'
patch/integrations/contacts/{contactId}

Update a contact

Permissão:contacts:manage

Only the fields sent are changed.

Parâmetros

NomeLocalTipoDescrição
contactIdobrigatóriopathstring · uuid

Corpo da requisição (application/json)

IntegrationUpdateContactDto

NomeTipoDescrição
nameopcionalstring

length 1–120

phoneNumberopcionalstring

Phone in international format; stored as E.164.

length 1–32

emailopcionalstring · emailpode ser null

null clears it.

length 0–255

identifieropcionalstringpode ser null

Your own identifier for this contact; null clears it.

length 0–255

customAttributesopcionalobject

Values keyed by custom attribute key.

Respostas

200

The updated contact.

IntegrationContact

NomeTipoDescrição
idobrigatóriostring · uuid
nameobrigatóriostringpode ser null
phoneNumberobrigatóriostringpode ser null

E.164 with +, or null.

emailobrigatóriostring · emailpode ser null
identifierobrigatóriostringpode ser null

Your own identifier for this contact (e.g. CRM id).

customAttributesobrigatórioobject

Values keyed by custom attribute key (see GET /integrations/custom-attributes).

createdAtobrigatóriostring · date-time
updatedAtobrigatóriostring · date-time
Exemplo
{
  "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"
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

Exemplos

CONTACT_ATTRIBUTE_INVALID
{
  "code": "CONTACT_ATTRIBUTE_INVALID",
  "message": "CONTACT_ATTRIBUTE_INVALID"
}
CONTACT_ATTRIBUTE_UNKNOWN
{
  "code": "CONTACT_ATTRIBUTE_UNKNOWN",
  "message": "CONTACT_ATTRIBUTE_UNKNOWN"
}
CONTACT_PHONE_INVALID
{
  "code": "CONTACT_PHONE_INVALID",
  "message": "CONTACT_PHONE_INVALID"
}
Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

404

The resource does not exist, belongs to another account or is outside the inboxes of the key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

CONTACT_NOT_FOUND
{
  "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.

409

The request conflicts with the current state of the resource.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

CONTACT_PHONE_EXISTS
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
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"
  }
}'

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

Custom attributes

get/integrations/custom-attributes

List custom attributes

Permissão:custom-attributes:read

Custom attribute definitions: the keys accepted in customAttributes.

Parâmetros

NomeLocalTipoDescrição
modelopcionalqueryCustomAttributeModel

Valores: "CONTACT""CONVERSATION"

pageopcionalqueryinteger

1-based page number.

Padrão: 1

min 1

limitopcionalqueryinteger

Items per page (max 100).

Padrão: 20

min 1 · max 100

Respostas

200

A page of custom attribute definitions.

NomeTipoDescrição
dataobrigatórioarray<IntegrationCustomAttribute>
metaobrigatórioIntegrationPageMeta
Exemplo
{
  "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
  }
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

IntegrationValidationError

NomeTipoDescrição
statusCodeobrigatórionumber
messageobrigatórioarray<string> | string

One entry per rejected body/query field, or a single string for an invalid path parameter.

errorobrigatóriostring

Exemplos

Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
curl 'https://api.talkvend.com/v1/integrations/custom-attributes' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'

Conversations

get/integrations/conversations

List conversations

Permissão:conversations:read

Conversations 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

NomeLocalTipoDescrição
statusopcionalqueryConversationStatus

Valores: "OPEN""SNOOZED""RESOLVED""PENDING"

inboxIdopcionalquerystring · uuid
contactIdopcionalquerystring · uuid
assigneeIdopcionalquerystring · uuid
labelIdopcionalquerystring · uuid
pageopcionalqueryinteger

1-based page number.

Padrão: 1

min 1

limitopcionalqueryinteger

Items per page (max 100).

Padrão: 20

min 1 · max 100

Respostas

200

A page of conversations.

NomeTipoDescrição
dataobrigatórioarray<IntegrationConversation>
metaobrigatórioIntegrationPageMeta
Exemplo
{
  "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
  }
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

IntegrationValidationError

NomeTipoDescrição
statusCodeobrigatórionumber
messageobrigatórioarray<string> | string

One entry per rejected body/query field, or a single string for an invalid path parameter.

errorobrigatóriostring

Exemplos

Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
curl 'https://api.talkvend.com/v1/integrations/conversations' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'
post/integrations/conversations

Start a conversation with a first message

Permissão:conversations:manageIdempotente

Sends 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

NomeLocalTipoDescrição
Idempotency-Keyopcionalheaderstring

Idempotency-Key (1–255 characters). Retrying with the same key and the same body within 24 h replays the original result instead of sending again.

length 1–255

Corpo da requisição (application/json)

IntegrationCreateConversationDto

NomeTipoDescrição
inboxIdobrigatóriostring · uuid
contactIdopcionalstring · uuid

Existing contact. Send exactly one of contactId or contact.

contactopcionalIntegrationConversationContactInput

Contact to find or create. Send exactly one of contactId or contact.

contentobrigatóriostring

length 1–100000

subjectopcionalstring

Required for e-mail inboxes; ignored by other channels.

length 1–998

assigneeIdopcionalstring · uuid

User to assign a new conversation to (active member of the inbox). Without it the conversation stays unassigned.

Respostas

201

The conversation and the message sent.

IntegrationCreateConversationResult

NomeTipoDescrição
conversationobrigatórioIntegrationConversation
messageobrigatórioIntegrationMessage
createdobrigatórioboolean

False when an open conversation with this contact in this inbox was reused.

Exemplo
{
  "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
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

Headers da resposta

Idempotent-Replayed string

Present (true) when this response replays the result of an earlier request with the same Idempotency-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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

Exemplos

CONTACT_PHONE_INVALID
{
  "code": "CONTACT_PHONE_INVALID",
  "message": "CONTACT_PHONE_INVALID"
}
CONVERSATION_ASSIGNEE_NOT_IN_INBOX
{
  "code": "CONVERSATION_ASSIGNEE_NOT_IN_INBOX",
  "message": "CONVERSATION_ASSIGNEE_NOT_IN_INBOX"
}
CONVERSATION_TARGET_INVALID
{
  "code": "CONVERSATION_TARGET_INVALID",
  "message": "CONVERSATION_TARGET_INVALID"
}
EMAIL_SUBJECT_REQUIRED
{
  "code": "EMAIL_SUBJECT_REQUIRED",
  "message": "EMAIL_SUBJECT_REQUIRED"
}
IDEMPOTENCY_KEY_INVALID
{
  "code": "IDEMPOTENCY_KEY_INVALID",
  "message": "IDEMPOTENCY_KEY_INVALID"
}
INBOX_CHANNEL_UNSUPPORTED
{
  "code": "INBOX_CHANNEL_UNSUPPORTED",
  "message": "INBOX_CHANNEL_UNSUPPORTED"
}
MESSAGE_CONTENT_TOO_LONG
{
  "code": "MESSAGE_CONTENT_TOO_LONG",
  "message": "MESSAGE_CONTENT_TOO_LONG"
}
Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

404

The resource does not exist, belongs to another account or is outside the inboxes of the key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

CONTACT_NOT_FOUND
{
  "code": "CONTACT_NOT_FOUND",
  "message": "CONTACT_NOT_FOUND"
}
INBOX_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.

409

The request conflicts with the current state of the resource.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

IDEMPOTENCY_REQUEST_IN_PROGRESS
{
  "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
  "message": "IDEMPOTENCY_REQUEST_IN_PROGRESS"
}
INBOX_FREE_TEXT_BLOCKED
{
  "code": "INBOX_FREE_TEXT_BLOCKED",
  "message": "INBOX_FREE_TEXT_BLOCKED"
}
META_OUTSIDE_WINDOW
{
  "code": "META_OUTSIDE_WINDOW",
  "message": "META_OUTSIDE_WINDOW"
}
WHATSAPP_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.

422

The request is well-formed but cannot be processed.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

IDEMPOTENCY_KEY_REUSED
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
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"
}'

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

get/integrations/conversations/{conversationId}

Get a conversation

Permissão:conversations:read

Parâmetros

NomeLocalTipoDescrição
conversationIdobrigatóriopathstring · uuid

Respostas

200

The conversation.

IntegrationConversation

NomeTipoDescrição
idobrigatóriostring · uuid
displayIdobrigatórionumber

Sequential number shown in the vend inbox.

inboxIdobrigatóriostring · uuid
contactIdobrigatóriostring · uuid
statusobrigatórioConversationStatus

Valores: "OPEN""SNOOZED""RESOLVED""PENDING"

assigneeIdobrigatóriostring · uuidpode ser null
snoozedUntilobrigatóriostring · date-timepode ser null
resolvedAtobrigatóriostring · date-timepode ser null
lastActivityAtobrigatóriostring · date-time
subjectobrigatóriostringpode ser null

E-mail subject (e-mail inboxes only).

labelsobrigatórioarray<IntegrationConversationLabel>
createdAtobrigatóriostring · date-time
updatedAtobrigatóriostring · date-time
Exemplo
{
  "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"
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

IntegrationValidationError

NomeTipoDescrição
statusCodeobrigatórionumber
messageobrigatórioarray<string> | string

One entry per rejected body/query field, or a single string for an invalid path parameter.

errorobrigatóriostring

Exemplos

Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

404

The resource does not exist, belongs to another account or is outside the inboxes of the key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

CONVERSATION_NOT_FOUND
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
curl 'https://api.talkvend.com/v1/integrations/conversations/00000000-0000-0000-0000-000000000000' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'
patch/integrations/conversations/{conversationId}

Update a conversation

Permissão:conversations:manage

Resolve, 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

NomeLocalTipoDescrição
conversationIdobrigatóriopathstring · uuid

Corpo da requisição (application/json)

IntegrationUpdateConversationDto

NomeTipoDescrição
statusopcionalConversationStatus

Valores: "OPEN""SNOOZED""RESOLVED""PENDING"

assigneeIdopcionalstring · uuidpode ser null

User to assign (must be an active member of the inbox); null unassigns.

snoozedUntilopcionalstring · date-timepode ser null

Snooze until this moment; null clears it.

Respostas

200

The updated conversation.

IntegrationConversation

NomeTipoDescrição
idobrigatóriostring · uuid
displayIdobrigatórionumber

Sequential number shown in the vend inbox.

inboxIdobrigatóriostring · uuid
contactIdobrigatóriostring · uuid
statusobrigatórioConversationStatus

Valores: "OPEN""SNOOZED""RESOLVED""PENDING"

assigneeIdobrigatóriostring · uuidpode ser null
snoozedUntilobrigatóriostring · date-timepode ser null
resolvedAtobrigatóriostring · date-timepode ser null
lastActivityAtobrigatóriostring · date-time
subjectobrigatóriostringpode ser null

E-mail subject (e-mail inboxes only).

labelsobrigatórioarray<IntegrationConversationLabel>
createdAtobrigatóriostring · date-time
updatedAtobrigatóriostring · date-time
Exemplo
{
  "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"
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

Exemplos

CONVERSATION_ASSIGNEE_NOT_IN_INBOX
{
  "code": "CONVERSATION_ASSIGNEE_NOT_IN_INBOX",
  "message": "CONVERSATION_ASSIGNEE_NOT_IN_INBOX"
}
CONVERSATION_SEGMENT_REQUIRED
{
  "code": "CONVERSATION_SEGMENT_REQUIRED",
  "message": "CONVERSATION_SEGMENT_REQUIRED"
}
CONVERSATION_SNOOZE_INVALID
{
  "code": "CONVERSATION_SNOOZE_INVALID",
  "message": "CONVERSATION_SNOOZE_INVALID"
}
CONVERSATION_STATUS_INVALID
{
  "code": "CONVERSATION_STATUS_INVALID",
  "message": "CONVERSATION_STATUS_INVALID"
}
Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

404

The resource does not exist, belongs to another account or is outside the inboxes of the key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

CONVERSATION_NOT_FOUND
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
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"
}'

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

post/integrations/conversations/{conversationId}/labels

Add a label to a conversation

Permissão:conversations:manage

Parâmetros

NomeLocalTipoDescrição
conversationIdobrigatóriopathstring · uuid

Corpo da requisição (application/json)

IntegrationAddLabelBody

NomeTipoDescrição
labelIdobrigatóriostring · uuid

Respostas

200

The conversation with its labels.

IntegrationConversation

NomeTipoDescrição
idobrigatóriostring · uuid
displayIdobrigatórionumber

Sequential number shown in the vend inbox.

inboxIdobrigatóriostring · uuid
contactIdobrigatóriostring · uuid
statusobrigatórioConversationStatus

Valores: "OPEN""SNOOZED""RESOLVED""PENDING"

assigneeIdobrigatóriostring · uuidpode ser null
snoozedUntilobrigatóriostring · date-timepode ser null
resolvedAtobrigatóriostring · date-timepode ser null
lastActivityAtobrigatóriostring · date-time
subjectobrigatóriostringpode ser null

E-mail subject (e-mail inboxes only).

labelsobrigatórioarray<IntegrationConversationLabel>
createdAtobrigatóriostring · date-time
updatedAtobrigatóriostring · date-time
Exemplo
{
  "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"
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

IntegrationValidationError

NomeTipoDescrição
statusCodeobrigatórionumber
messageobrigatórioarray<string> | string

One entry per rejected body/query field, or a single string for an invalid path parameter.

errorobrigatóriostring

Exemplos

Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

404

The resource does not exist, belongs to another account or is outside the inboxes of the key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

CONVERSATION_NOT_FOUND
{
  "code": "CONVERSATION_NOT_FOUND",
  "message": "CONVERSATION_NOT_FOUND"
}
LABEL_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.

409

The request conflicts with the current state of the resource.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

LABEL_CONVERSATION_ALREADY_EXISTS
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
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"
}'

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

delete/integrations/conversations/{conversationId}/labels/{labelId}

Remove a label from a conversation

Permissão:conversations:manage

Parâmetros

NomeLocalTipoDescrição
conversationIdobrigatóriopathstring · uuid
labelIdobrigatóriopathstring · uuid

Respostas

200

The conversation with its labels.

IntegrationConversation

NomeTipoDescrição
idobrigatóriostring · uuid
displayIdobrigatórionumber

Sequential number shown in the vend inbox.

inboxIdobrigatóriostring · uuid
contactIdobrigatóriostring · uuid
statusobrigatórioConversationStatus

Valores: "OPEN""SNOOZED""RESOLVED""PENDING"

assigneeIdobrigatóriostring · uuidpode ser null
snoozedUntilobrigatóriostring · date-timepode ser null
resolvedAtobrigatóriostring · date-timepode ser null
lastActivityAtobrigatóriostring · date-time
subjectobrigatóriostringpode ser null

E-mail subject (e-mail inboxes only).

labelsobrigatórioarray<IntegrationConversationLabel>
createdAtobrigatóriostring · date-time
updatedAtobrigatóriostring · date-time
Exemplo
{
  "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"
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

IntegrationValidationError

NomeTipoDescrição
statusCodeobrigatórionumber
messageobrigatórioarray<string> | string

One entry per rejected body/query field, or a single string for an invalid path parameter.

errorobrigatóriostring

Exemplos

Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

404

The resource does not exist, belongs to another account or is outside the inboxes of the key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

CONVERSATION_NOT_FOUND
{
  "code": "CONVERSATION_NOT_FOUND",
  "message": "CONVERSATION_NOT_FOUND"
}
LABEL_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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
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_...'
get/integrations/conversations/{conversationId}/messages

List messages of a conversation

Permissão:conversations:read

Oldest first.

Parâmetros

NomeLocalTipoDescrição
conversationIdobrigatóriopathstring · uuid
pageopcionalqueryinteger

1-based page number.

Padrão: 1

min 1

limitopcionalqueryinteger

Items per page (max 100).

Padrão: 20

min 1 · max 100

Respostas

200

A page of messages.

NomeTipoDescrição
dataobrigatórioarray<IntegrationMessage>
metaobrigatórioIntegrationPageMeta
Exemplo
{
  "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
  }
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

IntegrationValidationError

NomeTipoDescrição
statusCodeobrigatórionumber
messageobrigatórioarray<string> | string

One entry per rejected body/query field, or a single string for an invalid path parameter.

errorobrigatóriostring

Exemplos

Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

404

The resource does not exist, belongs to another account or is outside the inboxes of the key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

CONVERSATION_NOT_FOUND
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
curl 'https://api.talkvend.com/v1/integrations/conversations/00000000-0000-0000-0000-000000000000/messages' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'
post/integrations/conversations/{conversationId}/messages

Send a text message or internal note

Permissão:conversations:manageIdempotente

Signed 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

NomeLocalTipoDescrição
conversationIdobrigatóriopathstring · uuid
Idempotency-Keyopcionalheaderstring

Idempotency-Key (1–255 characters). Retrying with the same key and the same body within 24 h replays the original result instead of sending again.

length 1–255

Corpo da requisição (application/json)

IntegrationSendMessageDto

NomeTipoDescrição
contentobrigatóriostring

length 1–100000

isPrivateopcionalboolean

Internal note: kept in the conversation, never sent.

Padrão: false

Respostas

201

The message created.

IntegrationMessage

NomeTipoDescrição
idobrigatóriostring · uuid
conversationIdobrigatóriostring · uuid
inboxIdobrigatóriostring · uuid
typeobrigatórioMessageType

Valores: "INCOMING""OUTGOING""ACTIVITY""TEMPLATE"

contentTypeobrigatórioMessageContentType

Valores: "TEXT""IMAGE""AUDIO""VIDEO""FILE"

statusobrigatórioMessageStatus

Valores: "SENT""DELIVERED""READ""FAILED"

contentobrigatóriostringpode ser null
privateobrigatórioboolean

Internal note: visible to agents, never sent to the contact.

senderobrigatórioIntegrationMessageSenderpode ser null

Null for messages from the contact or from the system.

createdAtobrigatóriostring · date-time
Exemplo
{
  "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"
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

Headers da resposta

Idempotent-Replayed string

Present (true) when this response replays the result of an earlier request with the same Idempotency-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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

Exemplos

IDEMPOTENCY_KEY_INVALID
{
  "code": "IDEMPOTENCY_KEY_INVALID",
  "message": "IDEMPOTENCY_KEY_INVALID"
}
MESSAGE_CONTENT_TOO_LONG
{
  "code": "MESSAGE_CONTENT_TOO_LONG",
  "message": "MESSAGE_CONTENT_TOO_LONG"
}
Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

404

The resource does not exist, belongs to another account or is outside the inboxes of the key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

CONVERSATION_NOT_FOUND
{
  "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.

409

The request conflicts with the current state of the resource.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

IDEMPOTENCY_REQUEST_IN_PROGRESS
{
  "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
  "message": "IDEMPOTENCY_REQUEST_IN_PROGRESS"
}
META_OUTSIDE_WINDOW
{
  "code": "META_OUTSIDE_WINDOW",
  "message": "META_OUTSIDE_WINDOW"
}
WHATSAPP_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.

422

The request is well-formed but cannot be processed.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

IDEMPOTENCY_KEY_REUSED
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
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
}'

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

Messages

Labels

get/integrations/labels

List labels

Permissão:labels:read

Labels of the account, used to classify conversations.

Parâmetros

NomeLocalTipoDescrição
pageopcionalqueryinteger

1-based page number.

Padrão: 1

min 1

limitopcionalqueryinteger

Items per page (max 100).

Padrão: 20

min 1 · max 100

Respostas

200

A page of labels.

NomeTipoDescrição
dataobrigatórioarray<IntegrationLabel>
metaobrigatórioIntegrationPageMeta
Exemplo
{
  "data": [
    {
      "id": "6b7c8d9e-0f1a-4b2c-9d4e-5f6a7b8c9d0e",
      "title": "billing",
      "color": "#1F93FF",
      "description": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

IntegrationValidationError

NomeTipoDescrição
statusCodeobrigatórionumber
messageobrigatórioarray<string> | string

One entry per rejected body/query field, or a single string for an invalid path parameter.

errorobrigatóriostring

Exemplos

Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
curl 'https://api.talkvend.com/v1/integrations/labels' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'

Templates

get/integrations/templates

List message templates

Permissão:templates:read

WhatsApp message templates of the account. Only APPROVED templates can be sent.

Parâmetros

NomeLocalTipoDescrição
statusopcionalqueryTemplateStatus

Valores: "PENDING""APPROVED""REJECTED""PAUSED""DISABLED"

pageopcionalqueryinteger

1-based page number.

Padrão: 1

min 1

limitopcionalqueryinteger

Items per page (max 100).

Padrão: 20

min 1 · max 100

Respostas

200

A page of templates.

NomeTipoDescrição
dataobrigatórioarray<IntegrationTemplate>
metaobrigatórioIntegrationPageMeta
Exemplo
{
  "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
  }
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

IntegrationValidationError

NomeTipoDescrição
statusCodeobrigatórionumber
messageobrigatórioarray<string> | string

One entry per rejected body/query field, or a single string for an invalid path parameter.

errorobrigatóriostring

Exemplos

Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
curl 'https://api.talkvend.com/v1/integrations/templates' \
  -H 'Authorization: Bearer vk_live_XXXXXXXXXXXX_...'
post/integrations/templates/{templateId}/send

Send an approved WhatsApp template

Permissão:conversations:manageIdempotente

The 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

NomeLocalTipoDescrição
templateIdobrigatóriopathstring · uuid
Idempotency-Keyopcionalheaderstring

Idempotency-Key (1–255 characters). Retrying with the same key and the same body within 24 h replays the original result instead of sending again.

length 1–255

Corpo da requisição (application/json)

IntegrationSendTemplateDto

NomeTipoDescrição
conversationIdopcionalstring · uuid

Existing conversation (mode 1).

inboxIdopcionalstring · uuid

WhatsApp inbox to send from (modes 2 and 3).

contactIdopcionalstring · uuid

Existing contact (mode 2, with inboxId).

contactopcionalIntegrationTemplateContactInput

Contact to find or create (mode 3, with inboxId).

parametersopcionalmap<string, string>

Template variable values keyed by variable name.

Respostas

201

The template message created.

IntegrationMessage

NomeTipoDescrição
idobrigatóriostring · uuid
conversationIdobrigatóriostring · uuid
inboxIdobrigatóriostring · uuid
typeobrigatórioMessageType

Valores: "INCOMING""OUTGOING""ACTIVITY""TEMPLATE"

contentTypeobrigatórioMessageContentType

Valores: "TEXT""IMAGE""AUDIO""VIDEO""FILE"

statusobrigatórioMessageStatus

Valores: "SENT""DELIVERED""READ""FAILED"

contentobrigatóriostringpode ser null
privateobrigatórioboolean

Internal note: visible to agents, never sent to the contact.

senderobrigatórioIntegrationMessageSenderpode ser null

Null for messages from the contact or from the system.

createdAtobrigatóriostring · date-time
Exemplo
{
  "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"
}

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

Headers da resposta

Idempotent-Replayed string

Present (true) when this response replays the result of an earlier request with the same Idempotency-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.

400

Invalid request: a query/body field failed validation (statusCode/message[] shape) or a business rule rejected it (code/message shape).

Exemplos

IDEMPOTENCY_KEY_INVALID
{
  "code": "IDEMPOTENCY_KEY_INVALID",
  "message": "IDEMPOTENCY_KEY_INVALID"
}
TEMPLATE_CHANNEL_INVALID
{
  "code": "TEMPLATE_CHANNEL_INVALID",
  "message": "TEMPLATE_CHANNEL_INVALID"
}
TEMPLATE_SEND_PARAMS_INVALID
{
  "code": "TEMPLATE_SEND_PARAMS_INVALID",
  "message": "TEMPLATE_SEND_PARAMS_INVALID"
}
TEMPLATE_SEND_TARGET_INVALID
{
  "code": "TEMPLATE_SEND_TARGET_INVALID",
  "message": "TEMPLATE_SEND_TARGET_INVALID"
}
Field validation failed
{
  "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.

401

Missing, malformed, revoked or expired API key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INVALID
{
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID"
}
API_KEY_MISSING
{
  "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.

402

The account has a pending payment; API access is blocked until it is settled.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

ACCOUNT_PAYMENT_REQUIRED
{
  "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.

403

The API key lacks the permission this operation requires (see x-vend-permission).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_INSUFFICIENT_PERMISSION
{
  "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.

404

The resource does not exist, belongs to another account or is outside the inboxes of the key.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

CONTACT_NOT_FOUND
{
  "code": "CONTACT_NOT_FOUND",
  "message": "CONTACT_NOT_FOUND"
}
CONVERSATION_NOT_FOUND
{
  "code": "CONVERSATION_NOT_FOUND",
  "message": "CONVERSATION_NOT_FOUND"
}
INBOX_NOT_FOUND
{
  "code": "INBOX_NOT_FOUND",
  "message": "INBOX_NOT_FOUND"
}
TEMPLATE_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.

409

The request conflicts with the current state of the resource.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

IDEMPOTENCY_REQUEST_IN_PROGRESS
{
  "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
  "message": "IDEMPOTENCY_REQUEST_IN_PROGRESS"
}
INBOX_INACTIVE
{
  "code": "INBOX_INACTIVE",
  "message": "INBOX_INACTIVE"
}
TEMPLATE_INACTIVE
{
  "code": "TEMPLATE_INACTIVE",
  "message": "TEMPLATE_INACTIVE"
}
TEMPLATE_NOT_APPROVED
{
  "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.

422

The request is well-formed but cannot be processed.

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

IDEMPOTENCY_KEY_REUSED
{
  "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.

429

Rate limit exceeded (per key, per account or repeated authentication failures per IP).

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Exemplos

API_KEY_RATE_LIMITED
{
  "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.

Exemplo de requisição
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"
  }
}'

Exemplo gerado do schema — campos alternativos aparecem juntos; veja a descrição de cada campo.

Schemas

Schema

ChannelType

string

Valores: "API""WHATSAPP_CLOUD""EVOLUTION""EMAIL""MESSENGER""INSTAGRAM""TWILIO_SMS"

Schema

ConversationStatus

string

Valores: "OPEN""SNOOZED""RESOLVED""PENDING"

Schema

CustomAttributeModel

string

Valores: "CONTACT""CONVERSATION"

Schema

CustomAttributeType

string

Valores: "TEXT""NUMBER""DATE""LIST""CHECKBOX"

Schema

IntegrationAddLabelBody

NomeTipoDescrição
labelIdobrigatóriostring · uuid

Schema

IntegrationContact

NomeTipoDescrição
idobrigatóriostring · uuid
nameobrigatóriostringpode ser null
phoneNumberobrigatóriostringpode ser null

E.164 with +, or null.

emailobrigatóriostring · emailpode ser null
identifierobrigatóriostringpode ser null

Your own identifier for this contact (e.g. CRM id).

customAttributesobrigatórioobject

Values keyed by custom attribute key (see GET /integrations/custom-attributes).

createdAtobrigatóriostring · date-time
updatedAtobrigatóriostring · date-time

Schema

IntegrationConversation

NomeTipoDescrição
idobrigatóriostring · uuid
displayIdobrigatórionumber

Sequential number shown in the vend inbox.

inboxIdobrigatóriostring · uuid
contactIdobrigatóriostring · uuid
statusobrigatórioConversationStatus

Valores: "OPEN""SNOOZED""RESOLVED""PENDING"

assigneeIdobrigatóriostring · uuidpode ser null
snoozedUntilobrigatóriostring · date-timepode ser null
resolvedAtobrigatóriostring · date-timepode ser null
lastActivityAtobrigatóriostring · date-time
subjectobrigatóriostringpode ser null

E-mail subject (e-mail inboxes only).

labelsobrigatórioarray<IntegrationConversationLabel>
createdAtobrigatóriostring · date-time
updatedAtobrigatóriostring · date-time

Schema

IntegrationConversationContactInput

NomeTipoDescrição
nameobrigatóriostring

length 1–120

phoneNumberopcionalstringpode ser null

Phone in international format. null is the same as omitting it.

length 1–32

emailopcionalstring · emailpode ser null

null is the same as omitting it.

length 0–255

identifieropcionalstringpode ser null

null is the same as omitting it.

length 0–255

customAttributesopcionalobjectpode ser null

Values keyed by custom attribute key. null is the same as omitting it.

Schema

IntegrationConversationLabel

NomeTipoDescrição
idobrigatóriostring · uuid
titleobrigatóriostring

Schema

IntegrationCreateContactDto

NomeTipoDescrição
nameobrigatóriostring

length 1–120

phoneNumberopcionalstring

Phone in international format; stored as E.164.

length 1–32

emailopcionalstring · email

length 0–255

identifieropcionalstring

Your own identifier for this contact (e.g. CRM id).

length 0–255

customAttributesopcionalobject

Values keyed by custom attribute key.

Schema

IntegrationCreateConversationDto

NomeTipoDescrição
inboxIdobrigatóriostring · uuid
contactIdopcionalstring · uuid

Existing contact. Send exactly one of contactId or contact.

contactopcionalIntegrationConversationContactInput

Contact to find or create. Send exactly one of contactId or contact.

contentobrigatóriostring

length 1–100000

subjectopcionalstring

Required for e-mail inboxes; ignored by other channels.

length 1–998

assigneeIdopcionalstring · uuid

User to assign a new conversation to (active member of the inbox). Without it the conversation stays unassigned.

Schema

IntegrationCreateConversationResult

NomeTipoDescrição
conversationobrigatórioIntegrationConversation
messageobrigatórioIntegrationMessage
createdobrigatórioboolean

False when an open conversation with this contact in this inbox was reused.

Schema

IntegrationCustomAttribute

NomeTipoDescrição
idobrigatóriostring · uuid
keyobrigatóriostring

Key used in customAttributes.

displayNameobrigatóriostring
modelobrigatórioCustomAttributeModel

Valores: "CONTACT""CONVERSATION"

typeobrigatórioCustomAttributeType

Valores: "TEXT""NUMBER""DATE""LIST""CHECKBOX"

valuesobrigatórioarray<string>

Allowed values (list attributes only).

Schema

IntegrationError

NomeTipoDescrição
codeobrigatóriostring

Stable, machine-readable error code (DOMAIN_DETAIL).

messageobrigatóriostring

Same value as code. Map codes to your own messages.

detailsopcionalobject

Extra context, present only on a few codes.

Schema

IntegrationInbox

NomeTipoDescrição
idobrigatóriostring · uuid
nameobrigatóriostring
channelTypeobrigatórioChannelType

Valores: "API""WHATSAPP_CLOUD""EVOLUTION""EMAIL""MESSENGER""INSTAGRAM""TWILIO_SMS"

activeobrigatórioboolean

Schema

IntegrationLabel

NomeTipoDescrição
idobrigatóriostring · uuid
titleobrigatóriostring
colorobrigatóriostringpode ser null
descriptionobrigatóriostringpode ser null

Schema

IntegrationMe

NomeTipoDescrição
apiKeyobrigatórioIntegrationMeApiKey
accountobrigatórioIntegrationNamedRef
allInboxesobrigatórioboolean

True when the key is not restricted to specific inboxes (requires conversations:read-all).

inboxesobrigatórioarray<IntegrationNamedRef>

Inboxes the key is restricted to (empty when allInboxes).

rateLimitobrigatórioIntegrationMeRateLimit

Schema

IntegrationMeApiKey

NomeTipoDescrição
idobrigatóriostring · uuid
nameobrigatóriostring
prefixobrigatóriostring

Public part of the key (safe to log).

permissionsobrigatórioarray<string>

Schema

IntegrationMeRateLimit

NomeTipoDescrição
perMinuteobrigatórionumber

Requests per minute for this key.

accountPerMinuteobrigatórionumber

Requests per minute shared by every key of the account.

Schema

IntegrationMessage

NomeTipoDescrição
idobrigatóriostring · uuid
conversationIdobrigatóriostring · uuid
inboxIdobrigatóriostring · uuid
typeobrigatórioMessageType

Valores: "INCOMING""OUTGOING""ACTIVITY""TEMPLATE"

contentTypeobrigatórioMessageContentType

Valores: "TEXT""IMAGE""AUDIO""VIDEO""FILE"

statusobrigatórioMessageStatus

Valores: "SENT""DELIVERED""READ""FAILED"

contentobrigatóriostringpode ser null
privateobrigatórioboolean

Internal note: visible to agents, never sent to the contact.

senderobrigatórioIntegrationMessageSenderpode ser null

Null for messages from the contact or from the system.

createdAtobrigatóriostring · date-time

Schema

IntegrationMessageSender

NomeTipoDescrição
kindobrigatóriostring

A vend user (agent) or an API key.

Valores: "USER""API_KEY"

idobrigatóriostring · uuid
nameobrigatóriostringpode ser null

Schema

IntegrationNamedRef

NomeTipoDescrição
idobrigatóriostring · uuid
nameobrigatóriostring

Schema

IntegrationPageMeta

NomeTipoDescrição
pageobrigatórionumber

min 1

limitobrigatórionumber

min 1 · max 100

totalobrigatórionumber

min 0

totalPagesobrigatórionumber

min 0

Schema

IntegrationSendMessageDto

NomeTipoDescrição
contentobrigatóriostring

length 1–100000

isPrivateopcionalboolean

Internal note: kept in the conversation, never sent.

Padrão: false

Schema

IntegrationSendTemplateDto

NomeTipoDescrição
conversationIdopcionalstring · uuid

Existing conversation (mode 1).

inboxIdopcionalstring · uuid

WhatsApp inbox to send from (modes 2 and 3).

contactIdopcionalstring · uuid

Existing contact (mode 2, with inboxId).

contactopcionalIntegrationTemplateContactInput

Contact to find or create (mode 3, with inboxId).

parametersopcionalmap<string, string>

Template variable values keyed by variable name.

Schema

IntegrationTemplate

NomeTipoDescrição
idobrigatóriostring · uuid
nameobrigatóriostring
languageobrigatóriostring

Meta language code (e.g. pt_BR), not BCP-47.

categoryobrigatórioTemplateCategorypode ser null

Valores: "MARKETING""UTILITY""AUTHENTICATION"

statusobrigatórioTemplateStatuspode ser null

Valores: "PENDING""APPROVED""REJECTED""PAUSED""DISABLED"

variablesobrigatórioarray<object>

Template variables. Send values by variable name in parameters of POST /integrations/templates/{templateId}/send.

Schema

IntegrationTemplateContactInput

NomeTipoDescrição
nameobrigatóriostring

length 1–120

phoneNumberobrigatóriostring

Phone in international format.

length 1–32

emailopcionalstring · emailpode ser null

null is the same as omitting it.

length 0–255

identifieropcionalstringpode ser null

null is the same as omitting it.

length 0–255

customAttributesopcionalobjectpode ser null

Values keyed by custom attribute key. null is the same as omitting it.

Schema

IntegrationUpdateContactDto

NomeTipoDescrição
nameopcionalstring

length 1–120

phoneNumberopcionalstring

Phone in international format; stored as E.164.

length 1–32

emailopcionalstring · emailpode ser null

null clears it.

length 0–255

identifieropcionalstringpode ser null

Your own identifier for this contact; null clears it.

length 0–255

customAttributesopcionalobject

Values keyed by custom attribute key.

Schema

IntegrationUpdateConversationDto

NomeTipoDescrição
statusopcionalConversationStatus

Valores: "OPEN""SNOOZED""RESOLVED""PENDING"

assigneeIdopcionalstring · uuidpode ser null

User to assign (must be an active member of the inbox); null unassigns.

snoozedUntilopcionalstring · date-timepode ser null

Snooze until this moment; null clears it.

Schema

IntegrationValidationError

NomeTipoDescrição
statusCodeobrigatórionumber
messageobrigatórioarray<string> | string

One entry per rejected body/query field, or a single string for an invalid path parameter.

errorobrigatóriostring

Schema

MessageContentType

string

Valores: "TEXT""IMAGE""AUDIO""VIDEO""FILE"

Schema

MessageStatus

string

Valores: "SENT""DELIVERED""READ""FAILED"

Schema

MessageType

string

Valores: "INCOMING""OUTGOING""ACTIVITY""TEMPLATE"

Schema

TemplateCategory

string

Valores: "MARKETING""UTILITY""AUTHENTICATION"

Schema

TemplateStatus

string

Valores: "PENDING""APPROVED""REJECTED""PAUSED""DISABLED"