Guide patients to care

The conversation stream can emit a skill_code.cta event with a skillCode, widget, and optional text. Use that typed event to decide which approved action to present. Do not infer a care action from assistant prose.

Example call to action

event: skill_code.cta
data: {"type":"skill_code.cta","skillCode":"112","widget":"cta_doctor_visit_in_person_widget","text":"Book an in-person visit"}

The exact mapping from skillCode and widget to your interface is part of your integration. Agree on supported mappings with your Doctronic business or implementation contact and provide a safe fallback for values your application does not recognize.

Prepare the user for booking

Appointment creation requires:

A user record with firstName, lastName, and phoneNumber.
An address containing line1, city, state, and postalCode.
The chatId associated with the clinical conversation.
A US state in the appointment location.
A chat that is ready for appointment booking.

Set or replace the user's address with PUT /address/. Although the request accepts partial fields, booking rejects a missing or incomplete address.

Offer scheduled care

Request availability with GET /appointments/scheduled/available-slots/?state=NY.
Optionally bound the search with datetimeFrom and datetimeTo ISO 8601 timestamps.
Present one of the returned slots without changing its timestamp.
Book it with POST /appointments/scheduled/, using the same state.

Scheduled appointment request

{
  "chatId": "chat-id-from-the-consultation",
  "startsAt": "2026-08-20T15:00:00Z",
  "location": {
    "state": "NY"
  }
}

A slot can become unavailable between selection and booking. On 409 error.appointments.slot_unavailable, refresh availability and ask the user to choose again. Do not silently substitute another time.

Send a unique Idempotency-Key with the booking. If the response is lost, retry the same request body with the same key.

Offer ASAP care

Use POST /appointments/asap/ when the approved workflow calls for the next available care queue rather than a future slot.

ASAP appointment request

{
  "chatId": "chat-id-from-the-consultation",
  "location": {
    "state": "NY"
  }
}

There is no guaranteed wait time. A successful response includes waitingRoomUrl. The URL currently expires one hour after issuance and can rotate when reissued, so avoid treating it as a permanent identifier.

If booking returns 502 error.appointments.waiting_room_unavailable, the response can include an appointmentId for an appointment that was already booked. Retrieve that appointment before deciding what to show the user. If you retry the same booking request, reuse its idempotency key.

Track the appointment

Use the appointment resource, not local assumptions, to show current state:

GET /appointments/ lists the user's appointments.
GET /appointments/{appointment_id}/ retrieves the latest detail.
POST /appointments/{appointment_id}/cancel/ cancels a booking.
POST /appointments/{appointment_id}/reschedule/ moves a scheduled booking to a new slot.

The public status values are booked, cancelled, fulfilled, noshow, and unknown.

Booking, cancellation, and rescheduling accept Idempotency-Key. Use one key for one intended change, and preserve it across network retries. See Errors and retries.

Add a pharmacy when the workflow requires one

Search with POST /pharmacy/search/, then save a result using its seven-digit ncpdpId with PUT /pharmacy/. Setting a pharmacy requires firstName, lastName, dateOfBirth, and sex on the user record.

Safety signals take their own path

A guardian event is not a booking instruction. Route it through the safety behavior agreed for your integration, even if another event or message suggests a routine next step.