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.
Respostas
200Default Response
Campos e exemplo da resposta
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.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
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
201Default Response
Campos e exemplo da resposta
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.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.
Respostas
200Default Response
Campos e exemplo da resposta
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.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.
Corpo da requisiçãoapplication/json
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
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.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
Exemplo completo do corpo
JSON
{ "ids": [ "string" ], "action": "pause", "confirmRisk": true}Respostas
200Default Response
Campos e exemplo da resposta
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.