Agenda
Consulte os horários livres, marque, remarque e cancele pelo seu sistema, com as mesmas regras que a IA segue na conversa. Para o sistema da clínica, do salão ou da escola que já tem a agenda dele.
agenda · na conta com o pacote Agenda; marcar, ver os livres e remarcar pedem a agenda ligada no chatbotPacoteIntegrações (R$ 49 por mês, por conta, em preço de lançamento). Sem ele, a API responde 403 plan_not_allowed, menos no teste grátis, enquanto houver respostas de teste.| Rota | O que faz |
|---|---|
GET /v1/bots/{id}/agenda | Serviços, profissionais, regras e horário. |
GET /v1/bots/{id}/availability | Os horários livres de um serviço num dia. |
GET /v1/appointments | Os horários marcados, por período, situação e contato. |
POST /v1/appointments | Marca um horário (com Idempotency-Key). |
PATCH /v1/appointments/{id} | Remarca, aprova o pedido, ou marca compareceu e faltou. |
POST /v1/appointments/{id}/cancel | Cancela (ou recusa o pedido). |
apt_ (horário), svc_ (serviço), pro_ (profissional), como o bot_ e o ctc_ do resto da API. As datas e horas vão em ISO 8601 com o fuso; o dia dos livres, em AAAA-MM-DD no fuso do chatbot (timezone na agenda).GET/v1/bots/{id}/agenda
O que a IA usa para marcar: cada serviço com a duração, o preço (em centavos, ou null), o intervalo depois, as vagas e quem faz; cada profissional com o que faz e o horário próprio (ou null, o do chatbot); e as regras. hours é o horário de funcionamento: o dia da semana (0 é domingo) com os intervalos. Com a agenda desligada, a resposta vem com enabled: false.
curl "https://www.boavoz.com/api/v1/bots/bot_7c9e6679-7425-40de-944b-e07fc1f90ae7/agenda" \
-H "Authorization: Bearer $BOAVOZ_API_KEY"{
"bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"enabled": true,
"timezone": "America/Sao_Paulo",
"rules": {
"min_notice_minutes": 120,
"max_days_ahead": 30,
"slot_step_minutes": 30,
"change_until_minutes": 180,
"team_approves": false
},
"hours": {
"1": [
[
"09:00",
"12:00"
],
[
"13:00",
"19:00"
]
],
"2": [
[
"09:00",
"12:00"
],
[
"13:00",
"19:00"
]
],
"6": [
[
"09:00",
"14:00"
]
]
},
"services": [
{
"id": "svc_1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
"name": "Corte",
"duration_minutes": 30,
"price_cents": 4500,
"buffer_minutes": 0,
"capacity": 1,
"active": true,
"professional_ids": [
"pro_6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d"
]
}
],
"professionals": [
{
"id": "pro_6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
"name": "Léo",
"active": true,
"hours": null,
"service_ids": [
"svc_1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b"
]
}
]
}GET/v1/bots/{id}/availability
service_id e date são obrigatórios; professional_id, opcional (sem ele, os livres de todos que fazem o serviço). Vale o que vale para a IA: o serviço inteiro cabe no horário, sem bater com outro horário, folga, feriado ou vaga cheia, com a antecedência e os dias à frente das regras.
curl "https://www.boavoz.com/api/v1/bots/bot_7c9e6679-7425-40de-944b-e07fc1f90ae7/availability?service_id=svc_1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b&date=2026-11-21" \
-H "Authorization: Bearer $BOAVOZ_API_KEY"{
"bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"service_id": "svc_1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
"date": "2026-11-21",
"timezone": "America/Sao_Paulo",
"slots": [
{
"start_at": "2026-11-21T15:00:00.000Z",
"end_at": "2026-11-21T15:30:00.000Z",
"professional": {
"id": "pro_6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
"name": "Léo"
}
},
{
"start_at": "2026-11-21T15:30:00.000Z",
"end_at": "2026-11-21T16:00:00.000Z",
"professional": {
"id": "pro_6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
"name": "Léo"
}
}
]
}GET/v1/appointments
Por começo, de agora até 30 dias à frente; com from e to, o período pedido (até 92 dias). Filtros: bot_id, status (pending, booked, attended, no_show, canceled) e contact_id. Página de até 100 (limit), com next_cursor.
curl "https://www.boavoz.com/api/v1/appointments?bot_id=bot_7c9e6679-7425-40de-944b-e07fc1f90ae7&limit=20" \
-H "Authorization: Bearer $BOAVOZ_API_KEY"{
"data": [
{
"id": "apt_9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "booked",
"service": {
"id": "svc_1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
"name": "Corte",
"duration_minutes": 30,
"price_cents": 4500
},
"professional": {
"id": "pro_6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
"name": "Léo"
},
"start_at": "2026-11-21T15:00:00.000Z",
"end_at": "2026-11-21T15:30:00.000Z",
"contact_id": "ctc_9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
"conversation_id": null,
"source": "api",
"channel": null,
"note": null,
"confirmed_at": null,
"created_at": "2026-11-18T13:02:11.000Z"
}
],
"next_cursor": null
}| Campo | O que é |
|---|---|
status | pending: o pedido espera a equipe aprovar (“A equipe aprova antes”); booked: marcado; attended e no_show: compareceu e faltou; canceled. |
source | ai (a conversa), team (o painel), api ou buttons. |
confirmed_at | Quando a pessoa tocou em Confirmo no lembrete do WhatsApp. |
note | A observação da equipe (o contato não vê). |
POST/v1/appointments
Com a Idempotency-Key obrigatória: repetir o mesmo pedido não marca duas vezes. O horário marcado pela API vale direto, sem esperar a equipe aprovar. contact é {"id": "ctc_…"} de um contato do chatbot, ou {"phone", "name"} (o WhatsApp com o DDI e o DDD; o contato é criado se for novo). Sem professional_id, fica com quem estiver livre no começo pedido.
curl -X POST "https://www.boavoz.com/api/v1/appointments" \
-H "Authorization: Bearer $BOAVOZ_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3b9f2c8e-5a1d-4e7b-9c6f-2d8a4e1b7c90" \
-d '{
"bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"service_id": "svc_1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
"professional_id": "pro_6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
"start_at": "2026-11-21T15:00:00.000Z",
"contact": {
"phone": "5511999990000",
"name": "Teste Postman"
},
"notify": false
}'{
"id": "apt_9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "booked",
"service": {
"id": "svc_1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
"name": "Corte",
"duration_minutes": 30,
"price_cents": 4500
},
"professional": {
"id": "pro_6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
"name": "Léo"
},
"start_at": "2026-11-21T15:00:00.000Z",
"end_at": "2026-11-21T15:30:00.000Z",
"contact_id": "ctc_9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
"conversation_id": null,
"source": "api",
"channel": null,
"note": null,
"confirmed_at": null,
"created_at": "2026-11-18T13:02:11.000Z",
"notification": null
}O começo que não está livre (outro marcou antes, folga, fora do horário ou das regras) volta com os livres mais perto:
curl -X POST "https://www.boavoz.com/api/v1/appointments" \
-H "Authorization: Bearer $BOAVOZ_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3b9f2c8e-5a1d-4e7b-9c6f-2d8a4e1b7c90" \
-d '{
"bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"service_id": "svc_1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
"professional_id": "pro_6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
"start_at": "2026-11-21T15:00:00.000Z",
"contact": {
"phone": "5511999990000"
}
}'{
"error": {
"code": "slot_unavailable",
"message": "Esse horário não está livre (outro marcou antes, folga, fora do horário ou das regras). Escolha um dos livres.",
"details": {
"alternatives": [
{
"start_at": "2026-11-21T15:30:00.000Z",
"end_at": "2026-11-21T16:00:00.000Z",
"professional": {
"id": "pro_6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
"name": "Léo"
}
}
]
}
}
}| Campo | Regra | Erro |
|---|---|---|
start_at | Um dos livres, em ISO 8601 com o fuso. | 400 start_at; 409 slot_unavailable |
notify | Com true, o contato recebe a confirmação na conversa: só dentro das 24 horas do WhatsApp e do Instagram (no chat do site, fica na conversa). notification diz como ficou: sent, outside_window, not_sent ou failed. | — |
note | Até 500 caracteres. | 400 note |
| outros campos | Não são aceitos. | 400 com o campo |
PATCH/v1/appointments/{id}
Um de cada vez: start_at (e, se quiser, professional_id) remarca para outro livre; status muda a situação: booked aprova o pedido que esperava a equipe, attended e no_show marcam compareceu e faltou, só depois do começo do horário (a última visita e a régua de quem faltou contam deles). Com notify: true, remarcar e aprovar avisam o contato.
curl -X PATCH "https://www.boavoz.com/api/v1/appointments/apt_9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b" \
-H "Authorization: Bearer $BOAVOZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"start_at": "2026-11-21T15:30:00.000Z"
}'{
"id": "apt_9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "booked",
"service": {
"id": "svc_1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
"name": "Corte",
"duration_minutes": 30,
"price_cents": 4500
},
"professional": {
"id": "pro_6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
"name": "Léo"
},
"start_at": "2026-11-21T15:30:00.000Z",
"end_at": "2026-11-21T16:00:00.000Z",
"contact_id": "ctc_9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
"conversation_id": null,
"source": "api",
"channel": null,
"note": null,
"confirmed_at": null,
"created_at": "2026-11-18T13:02:11.000Z",
"notification": null
}POST/v1/appointments/{id}/cancel
Libera a vaga. No pedido que esperava a equipe, vale como recusar. Com notify: true, o contato fica sabendo na conversa.
curl -X POST "https://www.boavoz.com/api/v1/appointments/apt_9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b/cancel" \
-H "Authorization: Bearer $BOAVOZ_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3b9f2c8e-5a1d-4e7b-9c6f-2d8a4e1b7c90" \
-d '{
"notify": false
}'{
"id": "apt_9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "canceled",
"service": {
"id": "svc_1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
"name": "Corte",
"duration_minutes": 30,
"price_cents": 4500
},
"professional": {
"id": "pro_6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
"name": "Léo"
},
"start_at": "2026-11-21T15:00:00.000Z",
"end_at": "2026-11-21T15:30:00.000Z",
"contact_id": "ctc_9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
"conversation_id": null,
"source": "api",
"channel": null,
"note": null,
"confirmed_at": null,
"created_at": "2026-11-18T13:02:11.000Z",
"notification": "sent"
}| Erro | Quando |
|---|---|
403 plan_not_allowed | A conta não tem o pacote Agenda (details.pack: agenda). |
422 agenda_not_enabled | A agenda está desligada no chatbot (marcar, ver os livres e remarcar). |
409 slot_unavailable | O começo não está livre; details.alternatives traz os livres mais perto. |
409 appointment_closed | O horário já foi cancelado ou concluído. |
409 invalid_transition | A situação não pode ir para a pedida (ex.: aprovar o que não é pedido, ou compareceu antes do começo, com details.reason not_started); details.status é a de agora. |
422 invalid_appointment | O serviço do horário saiu da agenda (cancele e marque outro). |
Cada mudança, venha da conversa, do painel ou da API, sai nos webhooks appointment.*. Pelo MCP, as mesmas rotas viram ferramentas: quem conecta o BoaVoz no Claude ou no ChatGPT pergunta “quem vem hoje à tarde?”.