Assistants

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 — 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)#

All sub-plans and fields are optional; omitted values use agent defaults, and null clears a stored value.

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} — 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.
• 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.

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#

• Prompts — reusable system prompts and global templates.
• Phone numbers — buy a number and link it via phoneNumberId.
• Calls — read call activity for your assistants.