Take bookings by phone

Create the bookings assistant#

Every assistant references a voice, a language model and a transcriber by ID. Quickstart walks through listing all three catalogues; if you already have the IDs, use them here.

curl -X POST https://core-api.heysadie.ai/assistants \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bookings",
    "voiceId": "VOICE_ID",
    "modelId": "MODEL_ID",
    "transcriberId": "TRANSCRIBER_ID",
    "firstMessage": "Riverside Bistro, this is Ava. Would you like to book a table?",
    "endOfCallMessage": "Thanks for calling. See you soon!",
    "developerPrompt": "You take table bookings for Riverside Bistro. We are open {{opening_hours}}. Take one booking per call. Never confirm a booking you have not collected every detail for, and never promise a table outside opening hours.",
    "parameters": { "opening_hours": "midday to 10pm, Tuesday to Sunday" },
    "categories": ["booking", "enquiry", "complaint"],
    "recordingEnabled": true,
    "toolIds": [],
    "timezone": "America/New_York",
    "address": "123 River Street, Springfield",
    "phoneNumberPassThrough": true
  }'

Three fields carry most of the behaviour. developerPrompt is your section of the instructions; parameters fills in its {{placeholders}}, so the opening hours live in one place instead of being retyped into the prompt every time they change. categories are the labels each call gets classified under, which is what makes "how many booking calls did we take last week" answerable afterwards.

The response returns the whole assistant object. Keep data.id (it is ASSISTANT_ID everywhere below) and notice that phoneNumberId comes back null. Nobody can reach this assistant yet.

Collect the booking details with a capture form#

A capture form is an ordered set of questions plus a trigger telling the assistant when they apply. Write the trigger as the caller's situation, not as a note to yourself: "the caller wants to book a table" is something the model can match a conversation against.

curl -X POST https://core-api.heysadie.ai/capture-forms \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "ASSISTANT_ID",
    "name": "Table booking",
    "trigger": "The caller wants to book a table, or change a booking they already have.",
    "introMessage": "Happy to book that in. I just need a few details.",
    "emailRecipients": ["[email protected]"],
    "fields": [
      {
        "key": "caller_name",
        "question": "What name should I put the booking under?",
        "type": "string",
        "required": true
      },
      {
        "key": "party_size",
        "question": "How many people will be dining?",
        "type": "number",
        "required": true
      },
      {
        "key": "booking_date",
        "question": "Which date would you like?",
        "type": "string",
        "required": true
      },
      {
        "key": "booking_time",
        "question": "And what time?",
        "type": "string",
        "required": true
      },
      {
        "key": "contact_number",
        "question": "What is the best number to reach you on?",
        "type": "string",
        "required": true
      },
      {
        "key": "notes",
        "question": "Is there anything we should know about, like allergies, a high chair, or a celebration?",
        "type": "string"
      }
    ],
    "isActive": true
  }'

Field keys are lowercase snake_case and unique within the form; a duplicate key is rejected. type is string or number, and required: true means the assistant asks again rather than letting an answer go missing. The one field left optional here is notes, because an optional question the caller skips is simply left out of the delivery.

The response is the stored form: its id, your fields in the order you sent them, isActive, and the recipients. Capture forms covers the rest of the field options, including options for restricting an answer to a fixed list of choices such as sitting times.

Give it a number to answer#

Search the provider inventory first. Only a number returned by that search can be purchased.

curl "https://core-api.heysadie.ai/phone-numbers/available?country=US" \
  -H "Authorization: ApiKey YOUR_API_KEY"

curl -X POST https://core-api.heysadie.ai/phone-numbers \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+12125550123",
    "name": "Bookings line"
  }'

The purchase response carries the number's id, phoneNumber, country, monthlySubscriptionCost and assistantName. The last of those is still null, because owning a number and answering calls on it are two different things. Keep data.id as PHONE_NUMBER_ID.

The link between the two lives on the assistant, not on the number:

curl -X PATCH https://core-api.heysadie.ai/assistants/ASSISTANT_ID \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumberId": "PHONE_NUMBER_ID" }'

The response echoes the assistant with phoneNumberId set. From this moment, calls to that number are answered by your assistant. The number is billed monthly until you release it with DELETE /phone-numbers/{id}. See Phone numbers.

Hand the caller to a person when they ask#

A transfer reason is one rule: this situation goes to that number. Add as many as you have scenarios; this one covers the caller who wants a human, whatever the topic.

curl -X POST https://core-api.heysadie.ai/transfer-reasons \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "ASSISTANT_ID",
    "name": "Caller wants a person",
    "reason": "The caller asks to speak to a person, or has a request the assistant cannot complete: a large group, a private hire, a complaint about a previous visit.",
    "message": "Of course. Let me put you through to the front desk.",
    "phoneNumber": "+15555550123",
    "isActive": true,
    "waitForResponse": true
  }'

reason is what the model matches the conversation against, so it is worth writing as generously as the example above: name the situations, not the category. message is spoken before the hand-off, and waitForResponse (default true) has the assistant wait for the caller before transferring. Later, PATCHing isActive: false retires a rule without losing its wording or its destination.

Keep the returned id. It comes back as transfer_reason_id on the end-of-call report whenever this rule fires, which is how you tell an escalated call from an ordinary one.

Send the results to your own server#

The assistant's serverUrl overrides your tenant-level webhook URL for this assistant only, which is what you want while you are still building.

curl -X PATCH https://core-api.heysadie.ai/assistants/ASSISTANT_ID \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "serverUrl": "https://YOUR-TUNNEL.ngrok.app/oncore/webhooks" }'

Receive call results on your server builds the receiver that URL points at, verification included. Skip this step if you would rather poll; the next step shows both routes.

Call it, then read what happened#

Dial your new number. You should hear the firstMessage in the voice you picked. Ask to book a table for four; answer the questions the assistant asks. When it has them all, the booking should land in the inbox you named in step 2, while you are still on the phone. Then say "actually, can I speak to someone?" and you should hear your transfer message before the front desk rings. Hang up.

The end-of-call report arrives at your serverUrl shortly afterwards. These are the fields that tell you how the call went:

Without a server, pull the same call over the API instead:

curl "https://core-api.heysadie.ai/calls?assistantId=ASSISTANT_ID&limit=1" \
  -H "Authorization: ApiKey YOUR_API_KEY"

data.calls[0] carries status, endedReason, callDuration, transcript, summary and supervisorAnswered, the REST API's camelCase counterpart of the report's snake_case. transcript and summary are produced after the call ends, so if they are still null, wait a moment and run the request again.