Create an assistant

An assistant is a configured AI voice agent that answers calls (and optionally texts) on behalf of your business. This guide walks the whole lifecycle: pick the building blocks, create the assistant, tune its behavior, attach knowledge and task flows, point webhooks at your server, and toggle the SMS channel.

For endpoint-by-endpoint request/response schemas, see the Assistants API reference.

Pick a voice, model, and transcriber#

Every assistant references three lookup resources by UUID:

All three lists support limit and offset query params, and each has a GET /{resource}/{id} detail endpoint.

curl "https://core-api.heysadie.ai/voices?limit=50" \
  -H "Authorization: ApiKey YOUR_API_KEY"

curl "https://core-api.heysadie.ai/models?limit=50" \
  -H "Authorization: ApiKey YOUR_API_KEY"

curl "https://core-api.heysadie.ai/transcribers?limit=50" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Keep the id of the voice, model, and transcriber you want. You'll pass them as voiceId, modelId, and transcriberId when creating the assistant.

To help you choose, each voice row carries optional language (the language codes that voice can speak with its underlying TTS model) and tags (guidance badges such as gender, accent, and personality). See Voices, Models & Transcribers. Voice display names are not unique (the same voice can appear once per underlying model), so always reference voices by id.

Create the assistant#

POST /assistants

curl -X POST https://core-api.heysadie.ai/assistants \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front Desk",
    "voiceId": "0195f1e2-...",
    "modelId": "0195f1e2-...",
    "transcriberId": "0195f1e2-...",
    "developerPrompt": "We are open {{opening_hours}}. Always ask for a callback number before ending the call.",
    "parameters": { "opening_hours": "10am to 10pm" },
    "firstMessage": "Hi! You have reached Joe'\''s Pizza. How can I help?",
    "endOfCallMessage": "Thanks for calling, and have a great day!",
    "recordingEnabled": true,
    "failoverNumber": "+15551234567",
    "failoverMode": false,
    "toolIds": [],
    "timezone": "Australia/Sydney",
    "address": "1 Example Street, Sydney",
    "phoneNumberPassThrough": true
  }'

Core field guide#

Conversation timing (settings.conversationConfig)#

Each time the caller pauses, the assistant judges whether they have finished. If it thinks they have, it waits minDelay seconds of silence and then replies. If it thinks they are still mid-sentence, it waits the longer maxDelay instead. A pause that sounds finished, such as the gap between digits of a phone number, gets the short wait. That is when an assistant cuts in, and raising minDelay is the fix. vadPlan tunes voice activity detection, the step that decides when sound counts as speech.

Every plan, and every field inside one, is optional. A field you leave out uses the default below. Times are in seconds.

To go back to a default, send null for the whole plan or for one field. The API deletes the stored value, and the next call uses the default. conversationConfig itself does not accept null. This body resets mode, minDelay and maxDelay together:

{
  "settings": {
    "conversationConfig": {
      "endpointingPlan": null
    }
  }
}

To reset one field and keep the others, send null for that field only, as in "endpointingPlan": { "minDelay": null }.

Speech delivery (settings.conversationConfig.deliveryMode)#

How expressive the assistant's voice sounds. One mode per assistant; the mode is read at call start, so a change applies from the next call.

With deliveryMode: "expressive", the optional expressiveOptions object (also under settings.conversationConfig) tunes the built-in defaults. Only the keys you set override a default; send expressiveOptions: null to clear all stored overrides.

Update the assistant#

PATCH /assistants/{id} applies a partial update; send only the fields you want to change. The body accepts the same fields as create.

curl -X PATCH https://core-api.heysadie.ai/assistants/ASSISTANT_ID \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "firstMessage": "Thanks for calling Joe'\''s! What can I do for you?" }'

Attach knowledge and task flows#

Once the assistant exists, wire in its supporting resources:

• Documents: attach knowledge-base documents with POST /assistants/{id}/documents. See Knowledge base. To narrow when lookup runs, see Control when the assistant looks up.
• Task groups: link structured task flows with POST /assistants/{id}/taskgroups and set per-assistant task overrides. See Task groups.
• Tools: set toolIds on the assistant (create or PATCH). See Tools.
• Custom instructions: add up to six short behavior tweaks. See Custom instructions.
• Capture forms: collect structured caller details. See Capture forms.

Point webhooks at your server (serverUrl)#

serverUrl is the per-assistant webhook URL override: set it (on create or PATCH) to receive call results on your own endpoint, e.g. the end-of-call report. notifications holds up to 10 additional webhook URLs. Remember that PATCHing notifications appends new URLs rather than replacing the list.

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://api.example.com/sadie/webhooks" }'

URLs are validated for safety at write time: unresolvable or disallowed hosts are rejected with a validation error.

To remove the override, PATCH serverUrl to null (an empty string works too); deliveries then fall back to your tenant-level webhook URL.

Enable or disable SMS#

PATCH /assistants/{id}/sms-enabled

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

• smsEnabled: true turns the SMS channel on; false turns it off.
• Enabling requires a linked Twilio phone number. The number is attached to the SMS sender pool automatically (idempotent). If no Twilio number is linked, the request fails with 400 (NO_PHONE_NUMBER_LINKED / NON_TWILIO_PROVIDER) and the flag is left unchanged.
• Disabling only clears the flag: the number intentionally stays registered for SMS so re-enabling doesn't require re-registration.
• The response returns the assistant id and its featureFlags map; other channel flags are preserved.

SMS traffic then shows up as conversations.

Enable or disable WhatsApp#

In the dashboard: finish Sign up to WhatsApp on the assistant, then turn WhatsApp Enabled on under Messaging and save.

PATCH /assistants/{id}/whatsapp-enabled

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

• whatsappEnabled: true turns the WhatsApp text channel on; false turns it off.
• Enabling requires a linked phone number that has been onboarded to WhatsApp. If no number is linked, or the number has no Meta phone-number ID, the request fails with 400 (NO_PHONE_NUMBER_LINKED / NUMBER_NOT_WHATSAPP_ONBOARDED) and the flag is left unchanged.
• Disabling only clears the flag. WABA registration is not undone.
• The response returns the assistant id and its featureFlags map; other channel flags are preserved.
• OnCore answers customer-initiated text only. It does not send templates or start a conversation.

WhatsApp threads then show up as conversations.

Delete the assistant#

DELETE /assistants/{id} deletes the assistant. Attached sub-resources (documents, task groups, overrides) are managed through their own endpoints.

curl -X DELETE https://core-api.heysadie.ai/assistants/ASSISTANT_ID \
  -H "Authorization: ApiKey YOUR_API_KEY"

Next steps#

• Expressive mode: pace, fillers, and nonverbal sounds on Cartesia, Fish Audio, xAI, and Inworld.
• Emotion tagging: one classifier-picked emotion per English reply on Sonic 3 / 3.5 / 3.6 and eleven_v3.
• Prompts: reusable system prompts and global templates.
• Phone numbers: buy a number and link it via phoneNumberId.

New to this? Voice assistants explains what it does and when to use it, without the API detail.