Referencia de la API

Números de WhatsApp

Lista los números de WhatsApp de tu organización, consulta estado, calidad y límite de cada uno directamente en Meta y sigue el volumen de envíos.

5 operaciones
URL basehttps://api.messages.ccxcompany.co
AutenticaciónBearer con tu clave de API

El texto técnico de abajo viene del contrato público, openapi.json, en el idioma en que se escribió el contrato.

List WABA numbers in the current organization

GET/numbers

Returns a paginated list. Filters: status, qualityRating, limit, skip. Sorted by createdAt desc.

Parámetros

Campo	Dónde	Tipo	Descripción
`status`opcional	query	`string`	Valores:`availableconnecteddisconnectedflaggedpending`
`qualityRating`opcional	query	`string`	Valores:`greenyellowredunknown`
`limit`opcional	query	`integer`
`skip`opcional	query	`integer`

Respuestas

200Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`items`obligatorio	`object[]`
`items[].id`obligatorio	`string`	Branded Number id (`num_` prefix + 21 nano-id chars).
`items[].organizationId`obligatorio	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`items[].phoneNumberId`obligatorio	`string`	Meta phone_number_id from the WABA Graph API.
`items[].wabaId`obligatorio	`string`	Meta WhatsApp Business Account id.
`items[].displayPhone`obligatorio	`string`	E.164 phone number — PII_SENSITIVE, masked in cross-tenant responses.
`items[].status`obligatorio	`string`	Valores:`availableconnecteddisconnectedflaggedpending`
`items[].qualityRating`obligatorio	`string`	Valores:`greenyellowredunknown`
`items[].messagingTier`obligatorio	`string`	Valores:`tier_250tier_1ktier_2ktier_10ktier_100kunlimited`
`items[].rateLimit`obligatorio	`object`
`items[].rateLimit.perSecond`obligatorio	`integer`
`items[].rateLimit.perDay`obligatorio	`integer`
`items[].meta`obligatorio	`object`
`items[].meta.verifiedName`opcional	`string`	Display name registered with WhatsApp Business.
`items[].meta.byo`opcional	`boolean`	True when the number runs under the customer's own WABA.
`items[].meta.nameStatus`opcional	`string`	Situação do nome de exibição na Meta. Ausente ⇒ desconhecido (número sem sync). Não deduza aprovação da presença de `verifiedName`: a Meta devolve o nome mesmo quando o recusa.Valores:`approvedpendingrejectedexpirednone`
`items[].meta.partnerRemovedAt`opcional	`string \| null · date-time`	When Meta reported (`account_update` `PARTNER_REMOVED` or `PARTNER_APP_UNINSTALLED`) that the customer removed CCX from this number's account. Only a mark: status and history are untouched, but sending through this number is expected to fail. `null`/absent = no such report pending.
`items[].meta.partnerRemovedReason`opcional	`string \| null`	Which Meta event set `partnerRemovedAt`; set and cleared together with it: - `PARTNER_REMOVED` — the customer stopped sharing the account with CCX. - `PARTNER_APP_UNINSTALLED` — the customer uninstalled the CCX app (or removed its permissions), which revokes the token CCX sends with.Valores:`PARTNER_REMOVEDPARTNER_APP_UNINSTALLED`
`items[].profile`opcional	`object`
`items[].profile.about`opcional	`string`
`items[].profile.address`opcional	`string`
`items[].profile.email`opcional	`string`
`items[].profile.website`opcional	`string`
`items[].profile.vertical`opcional	`string`
`items[].profile.profilePictureUrl`opcional	`string`
`items[].lastMetaSyncAt`opcional	`string \| null · date-time`
`items[].createdAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.
`items[].updatedAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.
`total`obligatorio	`integer`

JSON

{  "items": [    {      "id": "num_aB3xY9zQ1pTkLmNoPqRsT",      "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",      "phoneNumberId": "1234567890123456",      "wabaId": "9876543210987654",      "displayPhone": "+5511999998888",      "status": "connected",      "qualityRating": "green",      "messagingTier": "tier_1k",      "rateLimit": {        "perSecond": 80,        "perDay": 100000      },      "meta": {        "verifiedName": "Acme Sales",        "byo": false,        "nameStatus": "rejected",        "partnerRemovedAt": "2026-10-16T12:00:00.000Z",        "partnerRemovedReason": "PARTNER_REMOVED"      },      "profile": {        "about": "string",        "address": "string",        "email": "string",        "website": "string",        "vertical": "string",        "profilePictureUrl": "string"      },      "lastMetaSyncAt": "2026-10-16T12:00:00.000Z",      "createdAt": "2026-04-07T17:30:00.000Z",      "updatedAt": "2026-04-07T17:30:00.000Z"    }  ],  "total": 3}

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

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

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

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Get a single WABA number

GET/numbers/{id}

Returns the full Number record for the given id. Tenant isolation is enforced by the Mongo Guardian filter — a request from another org receives 404, not the doc.

Parámetros

Campo	Dónde	Tipo	Descripción
`id`obligatorio	ruta	`string`	Branded Number id (`num_` prefix + 21 nano-id chars).

Respuestas

200Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`id`obligatorio	`string`	Branded Number id (`num_` prefix + 21 nano-id chars).
`organizationId`obligatorio	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`phoneNumberId`obligatorio	`string`	Meta phone_number_id from the WABA Graph API.
`wabaId`obligatorio	`string`	Meta WhatsApp Business Account id.
`displayPhone`obligatorio	`string`	E.164 phone number — PII_SENSITIVE, masked in cross-tenant responses.
`status`obligatorio	`string`	Valores:`availableconnecteddisconnectedflaggedpending`
`qualityRating`obligatorio	`string`	Valores:`greenyellowredunknown`
`messagingTier`obligatorio	`string`	Valores:`tier_250tier_1ktier_2ktier_10ktier_100kunlimited`
`rateLimit`obligatorio	`object`
`rateLimit.perSecond`obligatorio	`integer`
`rateLimit.perDay`obligatorio	`integer`
`meta`obligatorio	`object`
`meta.verifiedName`opcional	`string`	Display name registered with WhatsApp Business.
`meta.byo`opcional	`boolean`	True when the number runs under the customer's own WABA.
`meta.nameStatus`opcional	`string`	Situação do nome de exibição na Meta. Ausente ⇒ desconhecido (número sem sync). Não deduza aprovação da presença de `verifiedName`: a Meta devolve o nome mesmo quando o recusa.Valores:`approvedpendingrejectedexpirednone`
`meta.partnerRemovedAt`opcional	`string \| null · date-time`	When Meta reported (`account_update` `PARTNER_REMOVED` or `PARTNER_APP_UNINSTALLED`) that the customer removed CCX from this number's account. Only a mark: status and history are untouched, but sending through this number is expected to fail. `null`/absent = no such report pending.
`meta.partnerRemovedReason`opcional	`string \| null`	Which Meta event set `partnerRemovedAt`; set and cleared together with it: - `PARTNER_REMOVED` — the customer stopped sharing the account with CCX. - `PARTNER_APP_UNINSTALLED` — the customer uninstalled the CCX app (or removed its permissions), which revokes the token CCX sends with.Valores:`PARTNER_REMOVEDPARTNER_APP_UNINSTALLED`
`profile`opcional	`object`
`profile.about`opcional	`string`
`profile.address`opcional	`string`
`profile.email`opcional	`string`
`profile.website`opcional	`string`
`profile.vertical`opcional	`string`
`profile.profilePictureUrl`opcional	`string`
`lastMetaSyncAt`opcional	`string \| null · date-time`
`createdAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.
`updatedAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.

JSON

{  "id": "num_aB3xY9zQ1pTkLmNoPqRsT",  "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",  "phoneNumberId": "1234567890123456",  "wabaId": "9876543210987654",  "displayPhone": "+5511999998888",  "status": "connected",  "qualityRating": "green",  "messagingTier": "tier_1k",  "rateLimit": {    "perSecond": 80,    "perDay": 100000  },  "meta": {    "verifiedName": "Acme Sales",    "byo": false,    "nameStatus": "rejected",    "partnerRemovedAt": "2026-10-16T12:00:00.000Z",    "partnerRemovedReason": "PARTNER_REMOVED"  },  "profile": {    "about": "string",    "address": "string",    "email": "string",    "website": "string",    "vertical": "string",    "profilePictureUrl": "string"  },  "lastMetaSyncAt": "2026-10-16T12:00:00.000Z",  "createdAt": "2026-04-07T17:30:00.000Z",  "updatedAt": "2026-04-07T17:30:00.000Z"}

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

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

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

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Real-time health check from Meta

GET/numbers/{id}/health

Fetches current number status, quality, messaging tier, and business profile directly from Meta Graph API.

Parámetros

Campo	Dónde	Tipo	Descripción
`id`obligatorio	ruta	`string`	Branded Number id (`num_` prefix + 21 nano-id chars).

Respuestas

200Default Response
Campos y ejemplo de la respuesta
JSON
```
{}
```
401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

curl 'https://api.messages.ccxcompany.co/numbers/num_aB3xY9zQ1pTkLmNoPqRsT/health' \  -H "Authorization: Bearer $CCX_API_KEY"

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Envios reais deste número na janela pedida (default 24h)

GET/numbers/{id}/usage

Agrega messages (outbound, numberId) na janela. Aceita ?window=24h|7d|30d.

Parámetros

Campo	Dónde	Tipo	Descripción
`window`opcional	query	`string`
`id`obligatorio	ruta	`string`	Branded Number id (`num_` prefix + 21 nano-id chars).

Respuestas

200Default Response
Campos y ejemplo de la respuesta
Campo Tipo Descripción
windowobligatorio string
sentobligatorio integer
marketingSentopcional integer | null
sinceobligatorio string · date-time
untilobligatorio string · date-time
JSON
```
{  "window": "string",  "sent": 0,  "marketingSent": 0,  "since": "2026-10-16T12:00:00.000Z",  "until": "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).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

curl 'https://api.messages.ccxcompany.co/numbers/num_aB3xY9zQ1pTkLmNoPqRsT/usage' \  -H "Authorization: Bearer $CCX_API_KEY"

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Timeseries de envios (buckets pra sparkline)

GET/numbers/{id}/usage/timeseries

Retorna points[] alinhados no bucket pedido (hour|day). Buckets vazios entram como sent: 0 — o cliente pode desenhar direto.

Parámetros

Campo	Dónde	Tipo	Descripción
`window`opcional	query	`string`
`bucket`opcional	query	`string`	Valores:`hourday`
`id`obligatorio	ruta	`string`	Branded Number id (`num_` prefix + 21 nano-id chars).

Respuestas

200Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`window`obligatorio	`string`
`bucket`obligatorio	`string`	Valores:`hourday`
`since`obligatorio	`string · date-time`
`until`obligatorio	`string · date-time`
`points`obligatorio	`object[]`
`points[].at`obligatorio	`string · date-time`
`points[].sent`obligatorio	`integer`

JSON

{  "window": "string",  "bucket": "hour",  "since": "2026-10-16T12:00:00.000Z",  "until": "2026-10-16T12:00:00.000Z",  "points": [    {      "at": "2026-10-16T12:00:00.000Z",      "sent": 0    }  ]}

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

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

curl 'https://api.messages.ccxcompany.co/numbers/num_aB3xY9zQ1pTkLmNoPqRsT/usage/timeseries' \  -H "Authorization: Bearer $CCX_API_KEY"

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

¿Atascado en una ruta? Habla con quienes mantienen la API.

Empieza gratis Habla con ventas

Si creas la cuenta desde la web, recibes 5 US$ de crédito de prueba.

Campo	Tipo	Descripción
`window`obligatorio	`string`
`sent`obligatorio	`integer`
`marketingSent`opcional	`integer \| null`
`since`obligatorio	`string · date-time`
`until`obligatorio	`string · date-time`

Números de WhatsApp

List WABA numbers in the current organization

Parámetros

Respuestas

Ejemplo en curl

Get a single WABA number

Parámetros

Respuestas

Ejemplo en curl

Real-time health check from Meta

Parámetros

Respuestas

Ejemplo en curl

Envios reais deste número na janela pedida (default 24h)

Parámetros

Respuestas

Ejemplo en curl

Timeseries de envios (buckets pra sparkline)

Parámetros

Respuestas

Ejemplo en curl

Otras áreas de la API

¿Atascado en una ruta? Habla con quienes mantienen la API.