Empieza gratisEmpezar

Referencia de la API

schedule

Las operaciones de schedule en el contrato público de la API de CCX Messages: método, ruta, parámetros, cuerpo, respuestas y un ejemplo en curl para cada una.

  • 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.

Lista os agendamentos da organização

GET/v2/schedule

A FILA do que ainda vai sair: ordenada por hora do envio, crescente.

Sem status explícito, o já ENVIADO fica de fora — a tela é a fila, e por isso o seletor de status dela não tem 'Enviado'. Peça ?status=sent para ver o histórico.

Paginação por skip/limit (default 8, o mesmo da tela) porque o comp tem paginador NUMERADO — um cursor opaco não sabe dizer quantas páginas existem.

q casa nome do destinatário, destino, nome do template e prévia.

Filtros por contactId (o que está agendado para um contato), cardId (o que nasceu de um card) e serieId (as ocorrências de uma série que repete).

Com qualquer um deles — e sempre pela chave de API — a lista traz todos os canais, inclusive os de conversa (Instagram, Telegram, Messenger); sem eles, a tela de Agendamentos fica nos canais dela.

A ocorrência de uma série que o despachante PULOU por atraso (status: canceled, canceledReason: atrasada_demais) não é cancelamento de ninguém: só aparece com serieId, no lugar dela na série.

O destino sai MASCARADO para quem não tem pii:full, igual a Contatos.

Permissão: messages:read.

Parámetros

CampoDóndeTipoDescripción
channelopcionalquerystringValores:whatsappsmsemailrcsinstagramtelegrammessenger
statusopcionalquerystringValores:scheduledpausedsendingsentfailedcanceled
originopcionalquerystringValores:inboxautomationcampaignapi
qopcionalquerystring
fromopcionalquerystring · date-time
toopcionalquerystring · date-time
contactIdopcionalquerystring
cardIdopcionalquerystring
serieIdopcionalquerystring
limitopcionalqueryinteger
skipopcionalqueryinteger

Respuestas

  • 200Default Response

    Campos y ejemplo de la respuesta
    JSON
    {}
  • 400RFC 7807 problem details for BAD_REQUEST (400).

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

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

  • 422RFC 7807 problem details for VALIDATION_ERROR (422).

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/v2/schedule' \  -H "Authorization: Bearer $CCX_API_KEY"
Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Agenda uma mensagem para um contato

POST/v2/schedule

Valida no momento de SALVAR o que dá para saber agora: template existe e está aprovado, toda variável tem valor, o contato não pediu para não receber e a hora está no futuro. Um agendamento que só descobre o problema às 03:00 falha sem ninguém olhando.

O texto renderizado é CONGELADO na criação: editar o template depois não muda retroativamente o que a tela prometeu que sairia. As variáveis que vêm do card (cardId) também.

Conteúdo: templateId (template aprovado) OU text (texto livre), um dos dois.

  • Texto livre responde a uma conversa (conversationId; no WhatsApp, a do número com aquele telefone) e só sai se a hora cair ANTES de a janela dela fechar. Depois disso: 422 SCHEDULED_TEXT_OUTSIDE_WINDOW, com meta.janelaFechaEm e meta.efetivo — use um template.
  • Texto livre é uma resposta adiada: passa pelas portas da resposta imediata. Na sessão, exige também inbox:respond (403 SCHEDULED_TEXT_NEEDS_INBOX_RESPOND); pela chave, o messages:send do envio de texto da API. A conversa é conferida como na resposta: número desconectado, bot ou conta do Telegram e Página do Messenger indisponíveis respondem 412.
  • recorrencia ({ frequencia: diaria|semanal|mensal, fim }) só com template: com texto, 422 SCHEDULED_SERIES_NEEDS_TEMPLATE. A 1ª linha é a série (serieId = o próprio id, ocorrencia: 1).
  • cardId tem de ser um card desta organização (senão 404 CARD_NOT_FOUND) e do contato do agendamento (senão 422 SCHEDULED_CARD_CONTACT_MISMATCH).
  • cancelOnReply: true: mensagem do cliente antes da hora cancela o envio (e a série).

Silêncio: pedido entre 20h e 8h (Brasília) vira as 8h seguintes. A resposta traz horario: { pedido, efetivo, deslocou, silencio? } (ISO-8601). efetivo é o scheduledAt gravado; deslocou: true quando o pedido caiu no silêncio.

Idempotency-Key (header, opcional, 1 a 255 caracteres): o mesmo pedido com a mesma chave devolve o MESMO agendamento (200, sem agendar de novo); a primeira vez responde 201. A mesma chave com outro canal, destino ou tipo de conteúdo: 409 IDEMPOTENCY_KEY_REUSED.

Pela chave de API, a linha nasce com origin: "api" e createdById = o id da chave. Pela API, pede chave de produção (ccx_live_…): com chave de teste responde 403 SCHEDULE_REQUIRES_LIVE_KEY.

Permissão: messages:send.

Cuerpo de la peticiónapplication/json

CampoTipoDescripción
channelobligatoriostringValores:whatsappsmsemailinstagramtelegrammessenger
contactIdopcionalstring
toobligatoriostring
contactNameopcionalstring
numberIdopcionalstring
senderIdopcionalstring
smsRouteopcionalstringValores:premiumotpla_dedicada
fromAddressopcionalstring
templateIdopcionalstring
textopcionalstring
variablesopcionalobject
subjectopcionalstring
scheduledAtobligatoriostring · date-time
templateVarMapopcionalobject
cancelOnReplyopcionalboolean
recorrenciaopcionalobject
recorrencia.frequenciaobligatoriostringValores:diariasemanalmensal
recorrencia.fimobligatorioobject
recorrencia.fim.tipoopcionalstringValores:vezes
recorrencia.fim.ateopcionalstring
recorrencia.fim.vezesopcionalinteger
cardIdopcionalstring
conversationIdopcionalstring
Ejemplo completo del cuerpo
JSON
{  "channel": "whatsapp",  "contactId": "string",  "to": "string",  "contactName": "string",  "numberId": "string",  "senderId": "string",  "smsRoute": "premium",  "fromAddress": "string",  "templateId": "string",  "text": "string",  "variables": {},  "subject": "string",  "scheduledAt": "2026-10-16T12:00:00.000Z",  "templateVarMap": {},  "cancelOnReply": true,  "recorrencia": {    "frequencia": "diaria",    "fim": {      "tipo": "nunca"    }  },  "cardId": "string",  "conversationId": "string"}

Respuestas

  • 200Default Response

    Campos y ejemplo de la respuesta
    JSON
    {}
  • 201Default Response

    Campos y ejemplo de la respuesta
    JSON
    {}
  • 400RFC 7807 problem details for BAD_REQUEST (400).

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

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

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

  • 409RFC 7807 problem details for CONFLICT (409).

  • 412RFC 7807 problem details for PRECONDITION_FAILED (412).

  • 422RFC 7807 problem details for VALIDATION_ERROR (422).

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 -X POST 'https://api.messages.ccxcompany.co/v2/schedule' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Idempotency-Key: order-4821" \  -H "Content-Type: application/json" \  -d '{    "channel": "whatsapp",    "to": "string",    "scheduledAt": "2026-10-16T12:00:00.000Z"  }'
Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Detalhe de um agendamento

GET/v2/schedule/{id}

Agendamento de outra organização responde 404, como o que não existe.

Numa série que repete, serieId é o id da 1ª ocorrência e ocorrencia diz qual é esta (1, 2, 3…).

Permissão: messages:read.

Parámetros

CampoDóndeTipoDescripción
idobligatoriorutastring

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).

  • 422RFC 7807 problem details for VALIDATION_ERROR (422).

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/v2/schedule/<id>' \  -H "Authorization: Bearer $CCX_API_KEY"
Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Edita o conteúdo, a hora ou a repetição de um agendamento

PATCH/v2/schedule/{id}

O DESTINATÁRIO não é editável: trocar para quem vai a mensagem não é editar, é outro agendamento — e deixar o campo aqui faria o histórico do contato mentir sobre o que foi prometido a ele. O card também não.

Recusa com 409 SCHEDULED_NOT_EDITABLE o que já saiu (sent), está saindo (sending), falhou (failed: use reprocessar) ou foi cancelado.

  • Template: templateId, variables, subject, remetente, scheduledAt, cancelOnReply, recorrencia (null = esta é a última, para de repetir). Hora ou regra nova numa série: a série recomeça nesta linha.
  • Texto livre: só text, scheduledAt e cancelOnReply. A hora nova tem de cair antes de a janela fechar (422 SCHEDULED_TEXT_OUTSIDE_WINDOW). Texto não vira template nem o contrário (422 SCHEDULED_KIND_CHANGE); campo de template numa linha de texto: 422 SCHEDULED_TEXT_FIELD_NOT_EDITABLE. As mesmas portas da criação: inbox:respond na sessão (403 SCHEDULED_TEXT_NEEDS_INBOX_RESPOND) e a conversa conferida como na resposta imediata (412). Pela chave, só o texto que uma chave agendou (origin: "api"): o de uma pessoa responde 403 SCHEDULED_TEXT_NOT_FROM_API.

Silêncio: a hora nova entre 20h e 8h (Brasília) vira as 8h seguintes. A resposta traz horario: { pedido, efetivo, deslocou, silencio? } (ISO-8601). efetivo é o scheduledAt gravado; deslocou: true quando o pedido caiu no silêncio.

Agendamento de outra organização responde 404. Pela API, pede chave de produção (ccx_live_…): com chave de teste responde 403 SCHEDULE_REQUIRES_LIVE_KEY.

Permissão: messages:send.

Parámetros

CampoDóndeTipoDescripción
idobligatoriorutastring

Cuerpo de la peticiónapplication/json

CampoTipoDescripción
templateIdopcionalstring
textopcionalstring
variablesopcionalobject
subjectopcionalstring
scheduledAtopcionalstring · date-time
numberIdopcionalstring
senderIdopcionalstring
smsRouteopcionalstringValores:premiumotpla_dedicada
fromAddressopcionalstring
templateVarMapopcionalobject
cancelOnReplyopcionalboolean
recorrenciaopcionalobject | null
recorrencia.frequenciaobligatoriostringValores:diariasemanalmensal
recorrencia.fimobligatorioobject
recorrencia.fim.tipoopcionalstringValores:vezes
recorrencia.fim.ateopcionalstring
recorrencia.fim.vezesopcionalinteger
Ejemplo completo del cuerpo
JSON
{  "templateId": "string",  "text": "string",  "variables": {},  "subject": "string",  "scheduledAt": "2026-10-16T12:00:00.000Z",  "numberId": "string",  "senderId": "string",  "smsRoute": "premium",  "fromAddress": "string",  "templateVarMap": {},  "cancelOnReply": true,  "recorrencia": {    "frequencia": "diaria",    "fim": {      "tipo": "nunca"    }  }}

Respuestas

  • 200Default Response

    Campos y ejemplo de la respuesta
    JSON
    {}
  • 400RFC 7807 problem details for BAD_REQUEST (400).

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

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

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

  • 409RFC 7807 problem details for CONFLICT (409).

  • 412RFC 7807 problem details for PRECONDITION_FAILED (412).

  • 422RFC 7807 problem details for VALIDATION_ERROR (422).

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 -X PATCH 'https://api.messages.ccxcompany.co/v2/schedule/<id>' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'
Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Pausa, retoma, cancela ou reprocessa agendamentos

POST/v2/schedule/actions

Lote e individual pelo MESMO corpo: a barra de seleção manda N ids, o menu da linha manda um. Duas rotas para a mesma transição seriam duas cópias da tabela de estados legais.

A transição é compare-and-set sobre o estado esperado. Dois cliques no mesmo botão — ou um clique concorrente com o disparo do worker — mudam a linha UMA vez; o resto volta em skipped, e não vira envio duplicado. Id de outra organização também volta em skipped, sem mudar nada.

Série que repete: pausar, retomar e cancelar uma ocorrência valem para a SÉRIE inteira. Cancelar para a série: a repetição sai de toda ocorrência viva e as pendentes são canceladas (a que já está saindo sai, e não gera a próxima). Pausar segura a série até retomar (se uma ocorrência está saindo, a próxima já nasce pausada).

Retomar devolve as pausadas à fila; a que passou da hora sai uma vez, e as seguintes que já venceram são puladas (no máximo uma atrasada por série).

Texto livre e chave: a chave só pausa, retoma, cancela ou reprocessa texto livre que uma chave agendou (origin: "api"). Texto de uma pessoa (painel ou app) no lote: 403 SCHEDULED_TEXT_NOT_FROM_API com meta.ids, e nada muda.

retry é o reprocessamento manual, por ocorrência: zera as tentativas e manda ir agora.

💸 Quando a falha aconteceu DEPOIS de o provedor ser chamado (lastError.afterTransport), a mensagem pode ter sido entregue — e reprocessar manda de novo E COBRA de novo. Nesse caso a rota recusa com 412 e o corpo explica; repita com confirmRisk: true para assumir. A confirmação fica na auditoria.

Pela API, pede chave de produção (ccx_live_…): com chave de teste responde 403 SCHEDULE_REQUIRES_LIVE_KEY.

Permissão: messages:send.

Cuerpo de la peticiónapplication/json

CampoTipoDescripción
idsobligatoriostring[]
actionobligatoriostringValores:pauseresumecancelretry
confirmRiskopcionalboolean
Ejemplo completo del cuerpo
JSON
{  "ids": [    "string"  ],  "action": "pause",  "confirmRisk": true}

Respuestas

  • 200Default Response

    Campos y ejemplo de la respuesta
    JSON
    {}
  • 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).

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 -X POST 'https://api.messages.ccxcompany.co/v2/schedule/actions' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "ids": [      "string"    ],    "action": "pause"  }'
Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

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

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