Mensagens agendadas

Mensagens agendadas são as mesmas da Agenda do painel: o que você agenda pela API aparece lá, e a equipe pode ver e acompanhar. O despachante verifica a fila a cada minuto e envia as mensagens que chegaram no horário.

Use para lembretes de consulta, cobranças, follow-ups e renovações.

send_at precisa estar no futuro e em até 365 dias.
O texto aceita as variáveis {{nome}} e {{telefone}}, preenchidas com os dados do contato na hora do envio.
Até 10 anexos; o texto vira a legenda do primeiro anexo que aceita legenda.
Não disponível para conversas do Chat do site (webchat) nem para grupos.

O objeto mensagem agendada

{
  "id": "603916c7-604c-4c56-8a58-f3f76886634b",
  "object": "scheduled_message",
  "contact_id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
  "to": "5511999998888",
  "title": "Lembrete de consulta",
  "text": "Oi {{nome}}, passando para lembrar da sua consulta amanhã às 9h.",
  "media": [],
  "send_at": "2026-12-01T15:00:00Z",
  "status": "pending",
  "sent_at": null,
  "message_id": null,
  "error": null,
  "created_at": "2026-11-11T14:50:00Z",
  "updated_at": "2026-11-11T14:50:00Z"
}

Campo	Tipo	Descrição
`id`	UUID	ID da mensagem agendada.
`object`	string	Sempre `scheduled_message`.
`contact_id`	UUID ou `null`	Contato de destino.
`to`	string ou `null`	Telefone de destino.
`title`	string	Título na Agenda (padrão: “Mensagem via API”).
`text`	string ou `null`	Texto, com as variáveis ainda não substituídas.
`media`	lista	Anexos: cada um com `url`, `mime_type` e `filename`.
`send_at`	data	Quando deve ser enviada.
`status`	string	`pending`, `processing`, `sent`, `failed` ou `canceled`.
`sent_at`	data ou `null`	Quando foi enviada.
`message_id`	UUID ou `null`	A mensagem gerada no envio.
`error`	string ou `null`	Motivo da falha, quando `status` é `failed`.
`created_at`	data	Criação.
`updated_at`	data	Última alteração.

Status	Significado
`pending`	Esperando o horário. É o único status que pode ser cancelado.
`processing`	Sendo enviada agora.
`sent`	Enviada (veja `sent_at` e `message_id`).
`failed`	Não foi possível enviar (veja `error`).
`canceled`	Cancelada antes do envio.

Agendar mensagem

POST/v1/scheduled-messages

Programa uma mensagem para sair numa data e hora. Ela aparece na Agenda do painel e é enviada no horário pelo WhatsApp da conversa.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`to`	corpo	string	`to` ou `contact_id`	Telefone com DDI e DDD.
`contact_id`	corpo	UUID	`to` ou `contact_id`	Contato de destino.
`send_at`	corpo	data	sim	ISO 8601 com fuso (ex.: `2026-12-01T12:00:00-03:00`). No futuro e em até 365 dias.
`text`	corpo	string	`text` e/ou `media`	Até 4096 caracteres. Aceita `{{nome}}` e `{{telefone}}`.
`media`	corpo	lista	`text` e/ou `media`	Até 10 anexos, cada um com `url` (HTTPS pública), `type` (`image`, `video`, `audio`, `document`) e, opcionalmente, `filename`, `mime_type` e `voice_note`. O texto vira legenda do primeiro anexo que aceita legenda.
`title`	corpo	string	não	Título na Agenda (até 120 caracteres). Padrão: “Mensagem via API”.
`Idempotency-Key`	cabeçalho	string	não (recomendado)	Evita agendar duas vezes numa retentativa.

curl https://platform.toptalking.com.br/v1/scheduled-messages \
  -H "Authorization: Bearer $TOPTALKING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: consulta-987-lembrete" \
  -d '{
    "to": "5511999998888",
    "send_at": "2026-12-01T12:00:00-03:00",
    "title": "Lembrete de consulta",
    "text": "Oi {{nome}}, passando para lembrar da sua consulta amanhã às 9h."
  }'

const res = await fetch('https://platform.toptalking.com.br/v1/scheduled-messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'consulta-987-lembrete-mapa',
  },
  body: JSON.stringify({
    contact_id: '3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60',
    send_at: '2026-12-01T12:00:00-03:00',
    title: 'Lembrete de consulta',
    text: 'Oi {{nome}}, passando para lembrar da sua consulta amanhã às 9h. Segue o endereço:',
    media: [{ url: 'https://exemplo.com/mapa-clinica.png', type: 'image' }],
  }),
});
const agendada = await res.json();
console.log(agendada.id, agendada.status); // "pending"

import os
import requests

res = requests.post(
    "https://platform.toptalking.com.br/v1/scheduled-messages",
    headers={
        "Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}",
        "Idempotency-Key": "consulta-987-lembrete",
    },
    json={
        "to": "5511999998888",
        "send_at": "2026-12-01T12:00:00-03:00",
        "title": "Lembrete de consulta",
        "text": "Oi {{nome}}, passando para lembrar da sua consulta amanhã às 9h.",
    },
    timeout=30,
)
agendada = res.json()
if not res.ok:
    raise RuntimeError(f"{agendada['error']['code']}: {agendada['error']['message']}")

Resposta `201`

{
  "id": "603916c7-604c-4c56-8a58-f3f76886634b",
  "object": "scheduled_message",
  "contact_id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
  "to": "5511999998888",
  "title": "Lembrete de consulta",
  "text": "Oi {{nome}}, passando para lembrar da sua consulta amanhã às 9h.",
  "media": [],
  "send_at": "2026-12-01T15:00:00Z",
  "status": "pending",
  "sent_at": null,
  "message_id": null,
  "error": null,
  "created_at": "2026-11-11T14:50:00Z",
  "updated_at": "2026-11-11T14:50:00Z"
}

Erros

HTTP	`code`	Quando acontece
400	`missing_field`	Faltou `send_at`, `to`/`contact_id` ou `text`/`media`.
400	`invalid_field`	Campo inválido: `send_at` sem fuso, no passado ou a mais de 365 dias, mais de 10 anexos, texto longo demais, conversa do Chat do site ou de grupo…
400	`invalid_phone`	Telefone inválido.
403	`read_only_key`	Chave somente leitura.
404	`resource_not_found`	`contact_id` não encontrado.
409	`idempotency_conflict`	`Idempotency-Key` reutilizada com outro corpo.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_field",
    "message": "`send_at` precisa estar no futuro.",
    "param": "send_at",
    "request_id": "req_6f1d2c3b4a5e"
  }
}

Quando a mensagem for enviada (ou falhar), você recebe os webhooks scheduled_message.sent ou scheduled_message.failed.

Listar mensagens agendadas

GET/v1/scheduled-messages

As mensagens agendadas, ordenadas pelo horário de envio (as mais próximas primeiro). Use para mostrar a agenda de um cliente ou conferir o que ainda vai sair.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`status`	query	string	não	`pending`, `processing`, `sent`, `failed` ou `canceled`.
`contact_id`	query	UUID	não	Só as deste contato.
`limit`	query	inteiro	não	Itens por página, 1 a 100 (padrão 20).
`cursor`	query	string	não	`next_cursor` da página anterior.

curl "https://platform.toptalking.com.br/v1/scheduled-messages?status=pending&limit=50" \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

const res = await fetch(
  'https://platform.toptalking.com.br/v1/scheduled-messages?status=pending&limit=50',
  { headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` } },
);
const { data: pendentes } = await res.json();

import os
import requests

res = requests.get(
    "https://platform.toptalking.com.br/v1/scheduled-messages",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    params={"status": "pending", "limit": 50},
    timeout=30,
)
res.raise_for_status()
pendentes = res.json()["data"]

Resposta `200`

{
  "object": "list",
  "data": [
    {
      "id": "603916c7-604c-4c56-8a58-f3f76886634b",
      "object": "scheduled_message",
      "contact_id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
      "to": "5511999998888",
      "title": "Lembrete de consulta",
      "text": "Oi {{nome}}, passando para lembrar da sua consulta amanhã às 9h.",
      "media": [],
      "send_at": "2026-12-01T15:00:00Z",
      "status": "pending",
      "sent_at": null,
      "message_id": null,
      "error": null,
      "created_at": "2026-11-11T14:50:00Z",
      "updated_at": "2026-11-11T14:50:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Erros

Só os gerais: 401 (chave) e 429 (limite por minuto). Veja Erros.

Buscar mensagem agendada

GET/v1/scheduled-messages/{scheduled_message_id}

Uma mensagem agendada pelo ID. Use para saber se já saiu (status, sent_at) e qual mensagem ela gerou (message_id).

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`scheduled_message_id`	caminho	UUID	sim	ID da mensagem agendada.

curl https://platform.toptalking.com.br/v1/scheduled-messages/d3440bed-1a6f-4470-9d89-cec62fe2fc67 \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

const id = 'd3440bed-1a6f-4470-9d89-cec62fe2fc67';
const res = await fetch(`https://platform.toptalking.com.br/v1/scheduled-messages/${id}`, {
  headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` },
});
const agendada = await res.json();

import os
import requests

scheduled_id = "d3440bed-1a6f-4470-9d89-cec62fe2fc67"
res = requests.get(
    f"https://platform.toptalking.com.br/v1/scheduled-messages/{scheduled_id}",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
agendada = res.json()

Resposta `200`

Exemplo de uma mensagem que já foi enviada:

{
  "id": "d3440bed-1a6f-4470-9d89-cec62fe2fc67",
  "object": "scheduled_message",
  "contact_id": "721bfe94-e549-4354-b90c-a8d679e9b271",
  "to": "5521987654321",
  "title": "Renovação do plano",
  "text": "Oi {{nome}}! Seu plano vence na sexta. Quer que a gente renove?",
  "media": [],
  "send_at": "2026-11-10T13:00:00Z",
  "status": "sent",
  "sent_at": "2026-11-10T13:00:41Z",
  "message_id": "8e395744-cc4c-4eae-9ccd-06c8dde834e0",
  "error": null,
  "created_at": "2026-11-03T18:22:10Z",
  "updated_at": "2026-11-10T13:00:41Z"
}

Erros

HTTP	`code`	Quando acontece
404	`resource_not_found`	A mensagem agendada não existe.

Cancelar mensagem agendada

DELETE/v1/scheduled-messages/{scheduled_message_id}

Cancela uma mensagem que ainda está pending — ela some da fila e fica como cancelada na Agenda. A resposta é o item com status: "canceled".

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`scheduled_message_id`	caminho	UUID	sim	ID da mensagem agendada.

curl -X DELETE https://platform.toptalking.com.br/v1/scheduled-messages/603916c7-604c-4c56-8a58-f3f76886634b \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

const id = '603916c7-604c-4c56-8a58-f3f76886634b';
const res = await fetch(`https://platform.toptalking.com.br/v1/scheduled-messages/${id}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` },
});
const body = await res.json();
if (res.status === 409) console.log('Não dá mais para cancelar:', body.error.message);

import os
import requests

scheduled_id = "603916c7-604c-4c56-8a58-f3f76886634b"
res = requests.delete(
    f"https://platform.toptalking.com.br/v1/scheduled-messages/{scheduled_id}",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    timeout=30,
)
body = res.json()
if res.status_code == 409:
    print("Não dá mais para cancelar:", body["error"]["message"])

Resposta `200`

{
  "id": "603916c7-604c-4c56-8a58-f3f76886634b",
  "object": "scheduled_message",
  "contact_id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
  "to": "5511999998888",
  "title": "Lembrete de consulta",
  "text": "Oi {{nome}}, passando para lembrar da sua consulta amanhã às 9h.",
  "media": [],
  "send_at": "2026-12-01T15:00:00Z",
  "status": "canceled",
  "sent_at": null,
  "message_id": null,
  "error": null,
  "created_at": "2026-11-11T14:50:00Z",
  "updated_at": "2026-11-11T15:02:13Z"
}

Erros

HTTP	`code`	Quando acontece
403	`read_only_key`	Chave somente leitura.
404	`resource_not_found`	A mensagem agendada não existe.
409	`invalid_state`	A mensagem não está mais `pending` (já foi enviada, está sendo enviada, falhou ou já foi cancelada).

{
  "error": {
    "type": "conflict_error",
    "code": "invalid_state",
    "message": "Só é possível cancelar mensagens pendentes (status atual: sent).",
    "request_id": "req_6f1d2c3b4a5e"
  }
}

Mensagens agendadas

O objeto mensagem agendada

Agendar mensagem

Resposta 201

Erros

Listar mensagens agendadas

Resposta 200

Erros

Buscar mensagem agendada

Resposta 200

Erros

Cancelar mensagem agendada

Resposta 200

Erros

Resposta `201`

Resposta `200`

Resposta `200`

Resposta `200`