API reference

SMS

Send SMS with an Idempotency-Key, work out segments and price before sending, look up each message and read the replies (MO) your recipients sent back.

6 operations
Base URLhttps://api.messages.ccxcompany.co
AuthenticationBearer with your API key

The technical text below comes from the public contract, openapi.json, in the language the contract was written in.

Lista SMS

GET/v2/sms/messages

Ordem decrescente de criação. limit default 50, teto 200.

A lista é do ambiente da credencial que lê: uma chave ccx_test_* vê os envios de sandbox e nada mais. Para ler a produção, use uma chave ccx_live_*.

Permissão: sms:read.

Parameters

Field	In	Type	Description
`status`optional	query	`string`	Values:`queuedsendingsentdeliveredfailedundelivered`
`region`optional	query	`string`	Values:`BRINTL`
`contactId`optional	query	`string`
`campaignId`optional	query	`string`
`phone`optional	query	`string`
`from`optional	query	`string · date-time`
`to`optional	query	`string · date-time`
`limit`optional	query	`integer`
`skip`optional	query	`integer`

Responses

200Default Response

Response fields and example

Field	Type	Description
`items`required	`object[]`
`items[].id`required	`string`
`items[].status`required	`string`	Values:`queuedsendingsentdeliveredfailedundelivered`
`items[].env`required	`string`	Values:`livetest`
`items[].reason`optional	`string`	Values:`invalid_numbercarrier_rejectedblacklistedexpiredindeterminateabandoned`
`items[].route`optional	`string`	Values:`premiumotpla_dedicada`
`items[].to`required	`string`
`items[].provider`required	`string`	Values:`aws-snsaws-eumpontaltechccx-sandbox`
`items[].encoding`optional	`string`	Values:`GSM-7UCS-2`
`items[].length`optional	`integer`
`items[].segments`optional	`integer`
`items[].createdAt`required	`string · date-time`
`items[].sentAt`optional	`string · date-time`
`items[].deliveredAt`optional	`string · date-time`
`items[].failedAt`optional	`string · date-time`
`items[].providerReceipt`optional	`object`
`items[].providerReceipt.id`required	`string`
`items[].providerReceipt.type`required	`string`	Values:`api_messageapi_fastapi_reply`
`items[].providerReceipt.to`required	`string`
`items[].providerReceipt.message`optional	`string`
`items[].providerReceipt.reference`optional	`string`
`items[].providerReceipt.status`required	`string`
`items[].providerReceipt.statusDescription`required	`string`
`items[].providerReceipt.received`optional	`string`
`items[].providerReceipt.bill_factor`optional	`number`
`items[].providerReceipt.account_id`optional	`number`
`items[].providerReceipt.account_reference`optional	`string`
`items[].providerReceipt.channel`optional	`string \| null`	Values:`SMSRCSWHATSAPP`
`items[].contactId`optional	`string`
`items[].campaignId`optional	`string`
`items[].metadata`optional	`object`	Metadados de correlação do seu sistema (ex.: customerId, journeyId), devolvidos intactos em todo webhook desta mensagem. Até 20 chaves; chave começa por letra e usa [A-Za-z0-9_.-] (até 64); valor é texto (até 256), número ou booleano. Não envie dado pessoal aqui.
`total`required	`integer`

JSON

{  "items": [    {      "id": "string",      "status": "queued",      "env": "live",      "reason": "invalid_number",      "route": "premium",      "to": "string",      "provider": "aws-sns",      "encoding": "GSM-7",      "length": 0,      "segments": 1,      "createdAt": "2026-10-16T12:00:00.000Z",      "sentAt": "2026-10-16T12:00:00.000Z",      "deliveredAt": "2026-10-16T12:00:00.000Z",      "failedAt": "2026-10-16T12:00:00.000Z",      "providerReceipt": {        "id": "string",        "type": "api_message",        "to": "string",        "message": "string",        "reference": "string",        "status": "string",        "statusDescription": "string",        "received": "string",        "bill_factor": 0,        "account_id": 0,        "account_reference": "string",        "channel": "SMS"      },      "contactId": "string",      "campaignId": "string",      "metadata": {}    }  ],  "total": 0}

401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
422RFC 7807 problem details for VALIDATION_ERROR (422).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl 'https://api.messages.ccxcompany.co/v2/sms/messages' \  -H "Authorization: Bearer $CCX_API_KEY"

Required fields only. Swap the sample values for your own.

Envia um SMS

POST/v2/sms/messages

Envio síncrono: a resposta chega depois de o provedor aceitar (ou recusar) a mensagem. A entrega é assíncrona e chega no seu webhook como sms.delivered / sms.failed.

`Idempotency-Key` é obrigatória. Repetir a chave com o mesmo corpo devolve a resposta original com replayed: true e não envia nada; repetir com corpo diferente é 409.

Ambiente: vem da credencial. Uma chave ccx_test_* cai no sandbox, e env: "test" sai carimbado na resposta e no webhook. Não há como pedir um ambiente pelo corpo do request.

O sandbox mente em exatamente duas coisas, e a lista é fechada:

Nada chega em telefone nenhum.
O envio de sandbox não conta no seu volume mensal. O preço em billing.coins é o real de agora — mesma tabela, mesma faixa do seu volume de verdade —, mas um envio de teste nunca desloca a sua faixa. Consequência: no sandbox o preço não cai por causa de outro envio de sandbox.

Fora dessas duas, o sandbox é o produto: cobra de verdade (na carteira de sandbox), mesma contagem de segmentos, mesmo status, mesmos webhooks, mesma latência.

Finais mágicos (sandbox): salvo 0114, o número escolhe o DLR e não a resposta síncrona — validação nossa é síncrona, decisão do provedor é assíncrona.

final de `to`	webhook, ~3s depois
`0005`	`sms.delivered`
`0006`	`sms.undelivered`, `reason: "carrier_rejected"`
`0008`	`sms.failed`, `reason: "invalid_number"`
`0013`	`sms.failed`, `reason: "expired"`
`0018`	`sms.failed`, `reason: "blacklisted"`
`0099`	nenhum, nunca — para você exercitar o próprio timeout
`0114`	nenhum: recusa síncrona, `503 SERVICE_UNAVAILABLE` — o provedor ficou sem crédito, e o crédito é da CCX, não da sua carteira
qualquer outro	`sms.delivered`

encoding/length/segments são a contagem tarifável do Anexo I (A1.3) — a mesma que a fatura usa — do texto que sai: acento fora do GSM-7 é trocado pelo equivalente antes do envio (veja POST /v2/sms/preview). Um caractere sem equivalente (emoji, por exemplo) leva a mensagem inteira para UCS-2.

Preço: billing.coins é o custo do envio, em coins (1 coin = R$ 0,0001). É a soma do preço de CADA segmento — a faixa de volume pode virar no meio da mensagem (Cl. 8.12), então não é segments × preço do primeiro.

Saldo insuficiente é 402, e route: "la_dedicada" é 412: ela é sob consulta e não tem preço de tabela (Cl. 8.7.2). Use POST /v2/sms/preview para saber o preço antes de mandar.

429 `RATE_LIMITED`: duas causas, e as duas trazem o header Retry-After em segundos.

A sua conta passou do teto de SMS por segundo contratado. A recusa acontece antes do envio: nenhuma mensagem é criada.
O provedor de SMS limitou o envio (o limite é da rota, não da sua conta). Esse caso responde 429 com `Retry-After` — antes saía 502 DEPENDENCY_FAILED, sem dizer quando reenviar. A mensagem fica registrada com status failed e aparece em GET /v2/sms/messages/{id}.

Nos dois casos nada foi enviado nem cobrado: espere os segundos do Retry-After e reenvie. A Idempotency-Key é liberada, então o reenvio com a mesma chave é um envio novo (não um replay). No SMPP o mesmo 429 chega como ESME_RTHROTTLED: segure e reenvie.

Opt-out: na rota premium, destinatário cujo contato pediu para não receber comunicação é recusado com 422 e meta.motivo: "opt_out" — nada é gravado nem cobrado. A rota otp é transacional e sai sempre.

Permissão: sms:send.

Request body`application/json`

Field	Type	Description
`to`required	`string`
`body`required	`string`
`senderId`optional	`string`
`route`required	`string`	Rota tarifária (obrigatória): premium \| otp \| la_dedicada. la_dedicada é sob consulta (412).Values:`premiumotpla_dedicada`
`contactId`optional	`string`
`campaignId`optional	`string`
`metadata`optional	`object`	Metadados de correlação do seu sistema (ex.: customerId, journeyId), devolvidos intactos em todo webhook desta mensagem. Até 20 chaves; chave começa por letra e usa [A-Za-z0-9_.-] (até 64); valor é texto (até 256), número ou booleano. Não envie dado pessoal aqui.
`trackLinks`optional	`boolean`	true troca cada URL do texto por um link curto e publica `sms.clicked` a cada clique. O texto (e os segmentos) é contado depois da troca.

Full body example

JSON

{  "to": "string",  "body": "string",  "senderId": "string",  "route": "premium",  "contactId": "string",  "campaignId": "string",  "metadata": {},  "trackLinks": true}

Responses

201Default Response

Response fields and example

Field	Type	Description
`id`required	`string`
`status`required	`string`	Values:`queuedsendingsentdeliveredfailedundelivered`
`env`required	`string`	Values:`livetest`
`reason`optional	`string`	Values:`invalid_numbercarrier_rejectedblacklistedexpiredindeterminateabandoned`
`route`optional	`string`	Values:`premiumotpla_dedicada`
`to`required	`string`
`provider`required	`string`	Values:`aws-snsaws-eumpontaltechccx-sandbox`
`encoding`required	`string`	Values:`GSM-7UCS-2`
`length`required	`integer`
`segments`required	`integer`
`createdAt`required	`string · date-time`
`sentAt`optional	`string · date-time`
`deliveredAt`optional	`string · date-time`
`failedAt`optional	`string · date-time`
`providerReceipt`optional	`object`
`providerReceipt.id`required	`string`
`providerReceipt.type`required	`string`	Values:`api_messageapi_fastapi_reply`
`providerReceipt.to`required	`string`
`providerReceipt.message`optional	`string`
`providerReceipt.reference`optional	`string`
`providerReceipt.status`required	`string`
`providerReceipt.statusDescription`required	`string`
`providerReceipt.received`optional	`string`
`providerReceipt.bill_factor`optional	`number`
`providerReceipt.account_id`optional	`number`
`providerReceipt.account_reference`optional	`string`
`providerReceipt.channel`optional	`string \| null`	Values:`SMSRCSWHATSAPP`
`contactId`optional	`string`
`campaignId`optional	`string`
`metadata`optional	`object`	Metadados de correlação do seu sistema (ex.: customerId, journeyId), devolvidos intactos em todo webhook desta mensagem. Até 20 chaves; chave começa por letra e usa [A-Za-z0-9_.-] (até 64); valor é texto (até 256), número ou booleano. Não envie dado pessoal aqui.
`billing`optional	`object`
`billing.coins`required	`integer`
`replayed`required	`boolean`

JSON

{  "id": "string",  "status": "queued",  "env": "live",  "reason": "invalid_number",  "route": "premium",  "to": "string",  "provider": "aws-sns",  "encoding": "GSM-7",  "length": 0,  "segments": 1,  "createdAt": "2026-10-16T12:00:00.000Z",  "sentAt": "2026-10-16T12:00:00.000Z",  "deliveredAt": "2026-10-16T12:00:00.000Z",  "failedAt": "2026-10-16T12:00:00.000Z",  "providerReceipt": {    "id": "string",    "type": "api_message",    "to": "string",    "message": "string",    "reference": "string",    "status": "string",    "statusDescription": "string",    "received": "string",    "bill_factor": 0,    "account_id": 0,    "account_reference": "string",    "channel": "SMS"  },  "contactId": "string",  "campaignId": "string",  "metadata": {},  "billing": {    "coins": 0  },  "replayed": true}

400RFC 7807 problem details for BAD_REQUEST (400).
401RFC 7807 problem details for UNAUTHORIZED (401).
402RFC 7807 problem details for PAYMENT_REQUIRED (402).
403RFC 7807 problem details for FORBIDDEN (403).
409RFC 7807 problem details for CONFLICT (409).
412RFC 7807 problem details for PRECONDITION_FAILED (412).
422RFC 7807 problem details for VALIDATION_ERROR (422).
429RFC 7807 problem details for RATE_LIMITED (429).
502RFC 7807 problem details for DEPENDENCY_FAILED (502).
503RFC 7807 problem details for SERVICE_UNAVAILABLE (503).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl -X POST 'https://api.messages.ccxcompany.co/v2/sms/messages' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Idempotency-Key: order-4821" \  -H "Content-Type: application/json" \  -d '{    "to": "string",    "body": "string",    "route": "premium"  }'

Required fields only. Swap the sample values for your own.

Calcula segmentos e preço sem enviar

POST/v2/sms/preview

Não envia, não cobra e não conta volume — só o aceite conta (Cl. 7.2.1), então um preview não desloca a sua faixa.

body é o texto que chega ao aparelho: as rotas de SMS não entregam acento fora do GSM-7 (chegaria sem acento ou como @), então a CCX troca cada um pelo equivalente antes de enviar (ã → a, ç → c, aspas curvas → retas; é, à e ü, que o GSM-7 tem, ficam).

Se sobrar um caractere sem equivalente (emoji, por exemplo), o texto sai como veio. A troca nunca deixa a mensagem mais cara.

segments é a contagem tarifável do Anexo I (A1.3) sobre esse body, a mesma que a fatura usa: até 160 caracteres GSM-7 é 1 segmento, acima disso um a cada 152; um único caractere fora do GSM-7 leva a mensagem inteira para UCS-2, onde os limites são 70 e 67.

billing.coins é o preço no ambiente da credencial e no seu volume de agora. Sem route não há preço a aplicar e o bloco vem ausente; la_dedicada é 412.

Permissão: sms:send.

Request body`application/json`

Field	Type	Description
`body`required	`string`
`route`optional	`string`	Values:`premiumotpla_dedicada`

Full body example

JSON

{  "body": "string",  "route": "premium"}

Responses

200Default Response
Response fields and example
Field Type Description
bodyrequired string
encodingrequired string Values:GSM-7UCS-2
lengthrequired integer
segmentsrequired integer
billingoptional object
billing.coinsrequired integer
JSON
```
{  "body": "string",  "encoding": "GSM-7",  "length": 0,  "segments": 1,  "billing": {    "coins": 0  }}
```
400RFC 7807 problem details for BAD_REQUEST (400).
401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
412RFC 7807 problem details for PRECONDITION_FAILED (412).
422RFC 7807 problem details for VALIDATION_ERROR (422).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl -X POST 'https://api.messages.ccxcompany.co/v2/sms/preview' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "body": "string"  }'

Required fields only. Swap the sample values for your own.

Lê um SMS pelo id

GET/v2/sms/messages/{id}

O estado corrente da mensagem. Para reagir a mudanças, use o webhook — o polling aqui vê o mesmo dado mais tarde.

Permissão: sms:read.

Parameters

Field	In	Type	Description
`id`required	path	`string`

Responses

200Default Response

Response fields and example

Field	Type	Description
`id`required	`string`
`status`required	`string`	Values:`queuedsendingsentdeliveredfailedundelivered`
`env`required	`string`	Values:`livetest`
`reason`optional	`string`	Values:`invalid_numbercarrier_rejectedblacklistedexpiredindeterminateabandoned`
`route`optional	`string`	Values:`premiumotpla_dedicada`
`to`required	`string`
`provider`required	`string`	Values:`aws-snsaws-eumpontaltechccx-sandbox`
`encoding`optional	`string`	Values:`GSM-7UCS-2`
`length`optional	`integer`
`segments`optional	`integer`
`createdAt`required	`string · date-time`
`sentAt`optional	`string · date-time`
`deliveredAt`optional	`string · date-time`
`failedAt`optional	`string · date-time`
`providerReceipt`optional	`object`
`providerReceipt.id`required	`string`
`providerReceipt.type`required	`string`	Values:`api_messageapi_fastapi_reply`
`providerReceipt.to`required	`string`
`providerReceipt.message`optional	`string`
`providerReceipt.reference`optional	`string`
`providerReceipt.status`required	`string`
`providerReceipt.statusDescription`required	`string`
`providerReceipt.received`optional	`string`
`providerReceipt.bill_factor`optional	`number`
`providerReceipt.account_id`optional	`number`
`providerReceipt.account_reference`optional	`string`
`providerReceipt.channel`optional	`string \| null`	Values:`SMSRCSWHATSAPP`
`contactId`optional	`string`
`campaignId`optional	`string`
`metadata`optional	`object`	Metadados de correlação do seu sistema (ex.: customerId, journeyId), devolvidos intactos em todo webhook desta mensagem. Até 20 chaves; chave começa por letra e usa [A-Za-z0-9_.-] (até 64); valor é texto (até 256), número ou booleano. Não envie dado pessoal aqui.

JSON

{  "id": "string",  "status": "queued",  "env": "live",  "reason": "invalid_number",  "route": "premium",  "to": "string",  "provider": "aws-sns",  "encoding": "GSM-7",  "length": 0,  "segments": 1,  "createdAt": "2026-10-16T12:00:00.000Z",  "sentAt": "2026-10-16T12:00:00.000Z",  "deliveredAt": "2026-10-16T12:00:00.000Z",  "failedAt": "2026-10-16T12:00:00.000Z",  "providerReceipt": {    "id": "string",    "type": "api_message",    "to": "string",    "message": "string",    "reference": "string",    "status": "string",    "statusDescription": "string",    "received": "string",    "bill_factor": 0,    "account_id": 0,    "account_reference": "string",    "channel": "SMS"  },  "contactId": "string",  "campaignId": "string",  "metadata": {}}

401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl 'https://api.messages.ccxcompany.co/v2/sms/messages/<id>' \  -H "Authorization: Bearer $CCX_API_KEY"

Required fields only. Swap the sample values for your own.

Lista respostas (MO) aos seus SMS

GET/v2/sms/replies

As mensagens que os destinatários mandaram de volta aos SMS enviados por você, da mais recente para a mais antiga. limit default 50, teto 200. Use inReplyTo para as respostas a um SMS.

Cada resposta chega também no webhook como sms.received, e no bind SMPP (receiver/transceiver) que enviou o SMS original, como deliver_sm.

Short code compartilhado. As rotas premium e otp saem por short code compartilhado entre vários remetentes. Nele, quem associa a resposta ao SMS original é o provedor de envio, e a CCX não tem como conferir essa associação.

Preço: R$ 0,02 por resposta recebida, cobrado uma vez por resposta.

A lista é do ambiente da credencial que lê.

Permissão: sms:read.

Parameters

Field	In	Type
`inReplyTo`optional	query	`string`
`from`optional	query	`string · date-time`
`to`optional	query	`string · date-time`
`limit`optional	query	`integer`
`skip`optional	query	`integer`

Responses

200Default Response

Response fields and example

Field	Type	Description
`items`required	`object[]`
`items[].id`required	`string`
`items[].env`required	`string`	Values:`livetest`
`items[].inReplyTo`required	`string`
`items[].route`optional	`string`	Values:`premiumotpla_dedicada`
`items[].from`required	`string`
`items[].body`required	`string`
`items[].receivedAt`required	`string · date-time`
`items[].createdAt`required	`string · date-time`
`total`required	`integer`

JSON

{  "items": [    {      "id": "string",      "env": "live",      "inReplyTo": "string",      "route": "premium",      "from": "string",      "body": "string",      "receivedAt": "2026-10-16T12:00:00.000Z",      "createdAt": "2026-10-16T12:00:00.000Z"    }  ],  "total": 0}

401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
422RFC 7807 problem details for VALIDATION_ERROR (422).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl 'https://api.messages.ccxcompany.co/v2/sms/replies' \  -H "Authorization: Bearer $CCX_API_KEY"

Required fields only. Swap the sample values for your own.

Lê uma resposta (MO) pelo id

GET/v2/sms/replies/{id}

Uma resposta recebida. inReplyTo é o id do SMS ao qual ela responde.

Preço: R$ 0,02 por resposta recebida, cobrado uma vez por resposta.

Permissão: sms:read.

Parameters

Field	In	Type	Description
`id`required	path	`string`

Responses

200Default Response

Response fields and example

Field	Type	Description
`id`required	`string`
`env`required	`string`	Values:`livetest`
`inReplyTo`required	`string`
`route`optional	`string`	Values:`premiumotpla_dedicada`
`from`required	`string`
`body`required	`string`
`receivedAt`required	`string · date-time`
`createdAt`required	`string · date-time`

JSON

{  "id": "string",  "env": "live",  "inReplyTo": "string",  "route": "premium",  "from": "string",  "body": "string",  "receivedAt": "2026-10-16T12:00:00.000Z",  "createdAt": "2026-10-16T12:00:00.000Z"}

401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl 'https://api.messages.ccxcompany.co/v2/sms/replies/<id>' \  -H "Authorization: Bearer $CCX_API_KEY"

Required fields only. Swap the sample values for your own.

Stuck on a route? Talk to the people who run the API.

Start free Talk to sales

SMS

Lista SMS

Parameters

Responses

curl example

Envia um SMS

Request bodyapplication/json

Responses

curl example

Calcula segmentos e preço sem enviar

Request bodyapplication/json

Responses

curl example

Lê um SMS pelo id

Parameters

Responses

curl example

Lista respostas (MO) aos seus SMS

Parameters

Responses

curl example

Lê uma resposta (MO) pelo id

Parameters

Responses

curl example

Other API areas

Stuck on a route? Talk to the people who run the API.

Request body`application/json`

Request body`application/json`