Criar conta grátisCriar conta

Referência da API

schedule

As operações de schedule no contrato público da API da CCX Messages: método, caminho, parâmetros, corpo, respostas e um exemplo em curl para cada uma.

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

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

CampoOndeTipoDescrição
channelopcionalquerystringValores:whatsappsmsemailrcsinstagramtelegrammessenger
statusopcionalquerystringValores:scheduledpausedsendingsentfailedcanceled
originopcionalquerystringValores:inboxautomationcampaignapi
qopcionalquerystring
fromopcionalquerystring · date-time
toopcionalquerystring · date-time
contactIdopcionalquerystring
cardIdopcionalquerystring
serieIdopcionalquerystring
limitopcionalqueryinteger
skipopcionalqueryinteger

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    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).

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/v2/schedule' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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.

Corpo da requisiçãoapplication/json

CampoTipoDescrição
channelobrigatóriostringValores:whatsappsmsemailinstagramtelegrammessenger
contactIdopcionalstring
toobrigatóriostring
contactNameopcionalstring
numberIdopcionalstring
senderIdopcionalstring
smsRouteopcionalstringValores:premiumotpla_dedicada
fromAddressopcionalstring
templateIdopcionalstring
textopcionalstring
variablesopcionalobject
subjectopcionalstring
scheduledAtobrigatóriostring · date-time
templateVarMapopcionalobject
cancelOnReplyopcionalboolean
recorrenciaopcionalobject
recorrencia.frequenciaobrigatóriostringValores:diariasemanalmensal
recorrencia.fimobrigatórioobject
recorrencia.fim.tipoopcionalstringValores:vezes
recorrencia.fim.ateopcionalstring
recorrencia.fim.vezesopcionalinteger
cardIdopcionalstring
conversationIdopcionalstring
Exemplo completo do corpo
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"}

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    JSON
    {}
  • 201Default Response

    Campos e exemplo da resposta
    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).

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 -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"  }'
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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

CampoOndeTipoDescrição
idobrigatóriocaminhostring

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

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

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/v2/schedule/<id>' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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

CampoOndeTipoDescrição
idobrigatóriocaminhostring

Corpo da requisiçãoapplication/json

CampoTipoDescrição
templateIdopcionalstring
textopcionalstring
variablesopcionalobject
subjectopcionalstring
scheduledAtopcionalstring · date-time
numberIdopcionalstring
senderIdopcionalstring
smsRouteopcionalstringValores:premiumotpla_dedicada
fromAddressopcionalstring
templateVarMapopcionalobject
cancelOnReplyopcionalboolean
recorrenciaopcionalobject | null
recorrencia.frequenciaobrigatóriostringValores:diariasemanalmensal
recorrencia.fimobrigatórioobject
recorrencia.fim.tipoopcionalstringValores:vezes
recorrencia.fim.ateopcionalstring
recorrencia.fim.vezesopcionalinteger
Exemplo completo do corpo
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"    }  }}

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    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).

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 -X PATCH 'https://api.messages.ccxcompany.co/v2/schedule/<id>' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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.

Corpo da requisiçãoapplication/json

CampoTipoDescrição
idsobrigatóriostring[]
actionobrigatóriostringValores:pauseresumecancelretry
confirmRiskopcionalboolean
Exemplo completo do corpo
JSON
{  "ids": [    "string"  ],  "action": "pause",  "confirmRisk": true}

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    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).

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 -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"  }'
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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

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