Pular para o conteúdo
WbizTool

API v2 (beta)

Lembretes

Um lembrete envia a mesma mensagem a um destinatário várias e várias vezes, seguindo um agendamento: o aluguel todo mês, uma aula toda segunda-feira, um relatório toda noite. O agendamento é uma expressão cron de 5 partes em um fuso horário que você escolhe. Os lembretes criados pela API são os mesmos da página Lembretes do painel.

OperaçãoEndpointPermissão
Criar um lembretePOST /api/v2/remindersreminders
Listar lembretesGET /api/v2/remindersreminders
Obter um lembreteGET /api/v2/reminders/{id}reminders
Alterar, pausar ou retomarPATCH /api/v2/reminders/{id}reminders
Excluir um lembreteDELETE /api/v2/reminders/{id}reminders

Criar e alterar lembretes exige um plano que inclua lembretes; caso contrário, a resposta é 403 plan_required. Listar, ler, pausar e excluir funcionam em qualquer plano. Para uma mensagem que sai uma única vez em um horário definido, use send_at em Enviar uma mensagem.

Criar um lembrete#

POSThttps://wbiztool.com/api/v2/reminders

Corpo: JSON (application/json)

curl -X POST https://wbiztool.com/api/v2/reminders \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rent-flat-4b" \
  -d '{
    "name": "Weekly rent",
    "from": 101,
    "to": { "phone": "+919876543210" },
    "text": "Hi, a reminder that the rent is due on Friday.",
    "schedule": { "cron": "0 9 * * 1", "timezone": "Asia/Kolkata" }
  }'

Resposta (201):

{
  "id": 812,
  "name": "Weekly rent",
  "active": true,
  "to": { "phone": "+919876543210" },
  "from": 101,
  "text": "Hi, a reminder that the rent is due on Friday.",
  "media": null,
  "schedule": { "cron": "0 9 * * 1", "timezone": "Asia/Kolkata" },
  "next_run_at": "2026-10-19T09:00:00+05:30",
  "created_at": "2026-10-18T10:20:11.004Z"
}

Corpo

namestringobrigatório

Um nome para o lembrete, com até 100 caracteres, como aparece na página Lembretes.

toobjectobrigatório

Exatamente um entre phone (formato internacional com +), group (o nome exato de um grupo de WhatsApp), contact_id ou username (Telegram), como em Mensagens → Destinatários.

frominteger or nullObrigatório para uma chave limitada a alguns números

O id do número que envia o lembrete. Ele precisa estar conectado quando você o define. Omitido ou null: qualquer número conectado do espaço de trabalho envia.

textstringobrigatório

A mensagem, com até 3.000 caracteres. Também é a legenda quando media é enviado.

mediaobject or nullopcional

Uma imagem ou um arquivo para enviar a cada vez: url ou media_id e, opcionalmente, type, como em Mensagens → Mídia.

scheduleobjectobrigatório

cron (obrigatório) e timezone. Veja Agendamento.

activebooleanopcional

true (padrão) ativa o lembrete; false cria o lembrete pausado.

Agendamento#

schedule.cron tem cinco partes separadas por espaços: minuto, hora, dia do mês, mês e dia da semana. * significa "todo(a)". Precisa ser um agendamento que rode em algum momento (não 31 de fevereiro).

cronRoda
0 9 * * 1Às segundas-feiras às 09:00
30 18 * * *Todos os dias às 18:30
0 10 1 * *No dia 1º de cada mês às 10:00
0 9 * * 1-5De segunda a sexta às 09:00
0 8,20 * * *Todos os dias às 08:00 e às 20:00
0 9 15 1 *Em 15 de janeiro às 09:00, todo ano

schedule.timezone é o nome de um fuso horário IANA, como Asia/Kolkata, Europe/London ou America/New_York (padrão UTC). Os horários do cron estão nesse fuso, e next_run_at também vem nele, com o deslocamento. Veja a referência de fusos horários.

Cada execução envia uma mensagem como qualquer outra: precisa de mensagens restantes no plano e aparece em Listar mensagens.

Erros ao criar#

HTTPCódigoQuando
400validation_failedUm campo obrigatório está ausente ou vazio, um campo é desconhecido ou longo demais (name, to.group), ou media não é válido
400text_requiredtext está vazio
400text_too_longtext tem mais de 3.000 caracteres
400invalid_cronschedule.cron não tem 5 partes ou nunca roda
400invalid_timezoneschedule.timezone não é um fuso horário IANA
403plan_requiredO plano não inclui lembretes
403number_not_allowedA chave está limitada a alguns números e from não é um deles, ou está ausente
422invalid_phoneto.phone não é um número válido em formato internacional com +
422invalid_usernameto.username não é um nome de usuário do Telegram, um link nem um id tg:
422username_needs_telegramUm nome de usuário do Telegram, mas from não é uma conta do Telegram (ou, sem from, nenhuma conta do Telegram está conectada)
422contact_not_foundNenhum contato com esse to.contact_id
422media_not_foundNenhum arquivo com esse media.media_id
422invalid_media_urlmedia.url não é um link público http(s)
422number_not_connectedfrom não é um número conectado deste espaço de trabalho

Listar lembretes#

GEThttps://wbiztool.com/api/v2/reminders

Os lembretes do espaço de trabalho, do mais recente para o mais antigo, em páginas (limit de 1 a 100, padrão 25, e cursor). Os pausados estão incluídos, com "active": false. Uma chave limitada a alguns números vê apenas os lembretes enviados por eles.

curl "https://wbiztool.com/api/v2/reminders?limit=50" \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

A resposta é {"data": [Reminder, …], "next_cursor": "…" or null}.

Obter um lembrete#

GEThttps://wbiztool.com/api/v2/reminders/{id}
curl https://wbiztool.com/api/v2/reminders/812 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

Um lembrete que não existe, foi excluído ou é enviado por um número que a chave não pode usar responde 404 reminder_not_found.

Alterar, pausar ou retomar um lembrete#

PATCHhttps://wbiztool.com/api/v2/reminders/{id}

Corpo: JSON (application/json)

Envie só os campos que mudam; os outros mantêm seus valores. Os campos são os de Criar um lembrete. A resposta é 200 com o lembrete como ele ficou.

  • Pausar: {"active": false}. Ele para de rodar e next_run_at passa a ser null. Pausar funciona em qualquer plano.
  • Retomar: {"active": true}. Ele volta a rodar a partir do próximo horário. Retomar exige um plano com lembretes.
  • schedule é substituído por inteiro: envie cron junto. Sem timezone, o lembrete mantém o fuso atual.
# Pause
curl -X PATCH https://wbiztool.com/api/v2/reminders/812 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

# Move it to Fridays at 10:00 and change the text
curl -X PATCH https://wbiztool.com/api/v2/reminders/812 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schedule": {"cron": "0 10 * * 5"}, "text": "Hi, the rent is due today."}'

Uma alteração responde com os mesmos erros da criação, e com 404 reminder_not_found. Se um campo estiver errado, nada é alterado.

Excluir um lembrete#

DELETEhttps://wbiztool.com/api/v2/reminders/{id}

Exclui o lembrete: ele nunca mais roda. As mensagens que ele já enviou continuam no histórico. Para interrompê-lo só por um tempo, pause-o.

curl -X DELETE https://wbiztool.com/api/v2/reminders/812 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"
{ "id": 812, "deleted": true }

O objeto Reminder#

CampoTipoDescrição
idintegerO id do lembrete.
namestringO nome dele.
activebooleantrue enquanto roda, false enquanto está pausado.
toobjectO destinatário: phone (com +), group ou username. Um lembrete criado com contact_id mostra o número ou o grupo do contato.
frominteger or nullO id do número que envia, ou null para qualquer número conectado.
textstringA mensagem.
mediaobject or nulltype (image ou file), url e file_name.
scheduleobjectcron e timezone.
next_run_atstring or nullQuando ele roda da próxima vez, no fuso horário dele com o deslocamento, como 2026-10-19T09:00:00+05:30. null enquanto está pausado.
created_atstringQuando foi criado (UTC).

Relacionados#