StatusDesenvolvedoresParceirosPTENESEntrar
Falar com vendasCriar conta grátis
Criar conta grátis
Falar com vendasCriar conta grátis
EntrarStatusPTENES

Referência da API

Números de WhatsApp

Liste os números de WhatsApp da organização, veja status, qualidade e limite de cada um direto na Meta e acompanhe o volume de envios por período.

  • 5 operações
  • URL basehttps://api.messages.ccxcompany.co
  • AutenticaçãoBearer com a sua chave de API

O texto técnico abaixo vem do contrato público, o openapi.json, no idioma em que o contrato foi escrito.

List WABA numbers in the current organization

GET/numbers

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

Parâmetros

CampoOndeTipoDescrição
statusopcionalquerystringValores:availableconnecteddisconnectedflaggedpending
qualityRatingopcionalquerystringValores:greenyellowredunknown
limitopcionalqueryinteger
skipopcionalqueryinteger

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    itemsobrigatórioobject[]
    items[].idobrigatóriostringBranded Number id (num_ prefix + 21 nano-id chars).
    items[].organizationIdobrigatóriostringBranded Organization id (org_ prefix + 21 nano-id chars).
    items[].phoneNumberIdobrigatóriostringMeta phone_number_id from the WABA Graph API.
    items[].wabaIdobrigatóriostringMeta WhatsApp Business Account id.
    items[].displayPhoneobrigatóriostringE.164 phone number — PII_SENSITIVE, masked in cross-tenant responses.
    items[].statusobrigatóriostringValores:availableconnecteddisconnectedflaggedpending
    items[].qualityRatingobrigatóriostringValores:greenyellowredunknown
    items[].messagingTierobrigatóriostringValores:tier_250tier_1ktier_2ktier_10ktier_100kunlimited
    items[].rateLimitobrigatórioobject
    items[].rateLimit.perSecondobrigatóriointeger
    items[].rateLimit.perDayobrigatóriointeger
    items[].metaobrigatórioobject
    items[].meta.verifiedNameopcionalstringDisplay name registered with WhatsApp Business.
    items[].meta.byoopcionalbooleanTrue when the number runs under the customer's own WABA.
    items[].meta.nameStatusopcionalstringSituaçã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.partnerRemovedAtopcionalstring | null · date-timeWhen 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.partnerRemovedReasonopcionalstring | nullWhich 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[].profileopcionalobject
    items[].profile.aboutopcionalstring
    items[].profile.addressopcionalstring
    items[].profile.emailopcionalstring
    items[].profile.websiteopcionalstring
    items[].profile.verticalopcionalstring
    items[].profile.profilePictureUrlopcionalstring
    items[].lastMetaSyncAtopcionalstring | null · date-time
    items[].createdAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    items[].updatedAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    totalobrigatóriointeger
    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).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl 'https://api.messages.ccxcompany.co/numbers' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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

CampoOndeTipoDescrição
idobrigatóriocaminhostringBranded Number id (num_ prefix + 21 nano-id chars).

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    idobrigatóriostringBranded Number id (num_ prefix + 21 nano-id chars).
    organizationIdobrigatóriostringBranded Organization id (org_ prefix + 21 nano-id chars).
    phoneNumberIdobrigatóriostringMeta phone_number_id from the WABA Graph API.
    wabaIdobrigatóriostringMeta WhatsApp Business Account id.
    displayPhoneobrigatóriostringE.164 phone number — PII_SENSITIVE, masked in cross-tenant responses.
    statusobrigatóriostringValores:availableconnecteddisconnectedflaggedpending
    qualityRatingobrigatóriostringValores:greenyellowredunknown
    messagingTierobrigatóriostringValores:tier_250tier_1ktier_2ktier_10ktier_100kunlimited
    rateLimitobrigatórioobject
    rateLimit.perSecondobrigatóriointeger
    rateLimit.perDayobrigatóriointeger
    metaobrigatórioobject
    meta.verifiedNameopcionalstringDisplay name registered with WhatsApp Business.
    meta.byoopcionalbooleanTrue when the number runs under the customer's own WABA.
    meta.nameStatusopcionalstringSituaçã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.partnerRemovedAtopcionalstring | null · date-timeWhen 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.partnerRemovedReasonopcionalstring | nullWhich 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
    profileopcionalobject
    profile.aboutopcionalstring
    profile.addressopcionalstring
    profile.emailopcionalstring
    profile.websiteopcionalstring
    profile.verticalopcionalstring
    profile.profilePictureUrlopcionalstring
    lastMetaSyncAtopcionalstring | null · date-time
    createdAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    updatedAtobrigatóriostring · date-timeISO-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).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl 'https://api.messages.ccxcompany.co/numbers/num_aB3xY9zQ1pTkLmNoPqRsT' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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

CampoOndeTipoDescrição
idobrigatóriocaminhostringBranded Number id (num_ prefix + 21 nano-id chars).

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    JSON
    {}

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

  • 404RFC 7807 problem details for NOT_FOUND (404).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl 'https://api.messages.ccxcompany.co/numbers/num_aB3xY9zQ1pTkLmNoPqRsT/health' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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

CampoOndeTipoDescrição
windowopcionalquerystring
idobrigatóriocaminhostringBranded Number id (num_ prefix + 21 nano-id chars).

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    windowobrigatóriostring
    sentobrigatóriointeger
    marketingSentopcionalinteger | null
    sinceobrigatóriostring · date-time
    untilobrigatóriostring · 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).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl 'https://api.messages.ccxcompany.co/numbers/num_aB3xY9zQ1pTkLmNoPqRsT/usage' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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

CampoOndeTipoDescrição
windowopcionalquerystring
bucketopcionalquerystringValores:hourday
idobrigatóriocaminhostringBranded Number id (num_ prefix + 21 nano-id chars).

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    windowobrigatóriostring
    bucketobrigatóriostringValores:hourday
    sinceobrigatóriostring · date-time
    untilobrigatóriostring · date-time
    pointsobrigatórioobject[]
    points[].atobrigatóriostring · date-time
    points[].sentobrigatóriointeger
    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).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl 'https://api.messages.ccxcompany.co/numbers/num_aB3xY9zQ1pTkLmNoPqRsT/usage/timeseries' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Outras áreas da API

Travou em alguma rota? Fale com quem mantém a API.

Criar conta grátisFalar com vendas

Criando a conta pelo site, você ganha R$ 10 de crédito de teste.