BoaVoz
Documentação · API

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.

Permissão da chaveagenda · 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.
RotaO que faz
GET /v1/bots/{id}/agendaServiços, profissionais, regras e horário.
GET /v1/bots/{id}/availabilityOs horários livres de um serviço num dia.
GET /v1/appointmentsOs horários marcados, por período, situação e contato.
POST /v1/appointmentsMarca um horário (com Idempotency-Key).
PATCH /v1/appointments/{id}Remarca, aprova o pedido, ou marca compareceu e faltou.
POST /v1/appointments/{id}/cancelCancela (ou recusa o pedido).
Os ids
Os ids levam o prefixo: 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.

Serviços, profissionais, regras e horário
curl "https://www.boavoz.com/api/v1/bots/bot_7c9e6679-7425-40de-944b-e07fc1f90ae7/agenda" \
  -H "Authorization: Bearer $BOAVOZ_API_KEY"
Resposta · 200
{
  "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.

Os horários livres de um dia
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"
Resposta · 200
{
  "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.

Os horários marcados
curl "https://www.boavoz.com/api/v1/appointments?bot_id=bot_7c9e6679-7425-40de-944b-e07fc1f90ae7&limit=20" \
  -H "Authorization: Bearer $BOAVOZ_API_KEY"
Resposta · 200
{
  "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
}
CampoO que é
statuspending: o pedido espera a equipe aprovar (“A equipe aprova antes”); booked: marcado; attended e no_show: compareceu e faltou; canceled.
sourceai (a conversa), team (o painel), api ou buttons.
confirmed_atQuando a pessoa tocou em Confirmo no lembrete do WhatsApp.
noteA 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.

Marcar um horário
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
}'
Resposta · 201
{
  "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:

O horário que já foi marcado
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"
  }
}'
Resposta · 409
{
  "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"
          }
        }
      ]
    }
  }
}
CampoRegraErro
start_atUm dos livres, em ISO 8601 com o fuso.400 start_at; 409 slot_unavailable
notifyCom 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.—
noteAté 500 caracteres.400 note
outros camposNã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.

Remarcar
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"
}'
Resposta · 200
{
  "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.

Cancelar
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
}'
Resposta · 200
{
  "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"
}
ErroQuando
403 plan_not_allowedA conta não tem o pacote Agenda (details.pack: agenda).
422 agenda_not_enabledA agenda está desligada no chatbot (marcar, ver os livres e remarcar).
409 slot_unavailableO começo não está livre; details.alternatives traz os livres mais perto.
409 appointment_closedO horário já foi cancelado ou concluído.
409 invalid_transitionA 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_appointmentO 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?”.