Create an assistant

Creates a new assistant and provisions a phone number for it. The phone_number field on the response is assigned by the platform - callers cannot set or change it via this API. To use one of your organization's purchased numbers instead, send its id from GET /phone-numbers as phone_number_id: a number that is not available to your organization returns 404, one taken meanwhile 409. Cross-resource refs (prompt_id, knowledge_group_ids, etc.) are validated to belong to your organization before the assistant is saved.

Authorization

bearerAuth

AuthorizationBearer <token>

API key in the Authorization: Bearer <key> header. Keys are created in the SMAO dashboard (Settings → API Keys).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

phone_number_id?string

A purchased number from GET /phone-numbers. Omit it to have a number allocated automatically. It is not stored on the assistant.

Match^[a-fA-F0-9]{24}$

name*string

Length1 <= length <= 100

description?string

Lengthlength <= 500

Default""

language*string

BCP-47-ish language code from the platform-supported list.

Value in

"de"
"en"
"fr"
"it"
"de-CH"
"es"
"pt"
"tr"
"sv"
"fi"

voice_id*string

Voice ID. Must be one of the values returned by GET /voices; an unknown or unavailable ID returns 400.

company_name*string

Length1 <= length <= 200

company_industry*string

Length1 <= length <= 200

introduction*string

Opening text in the assistant language. The platform stores it as the canonical original localized introduction and generates other supported-language variants asynchronously. It is the whole greeting; the assistant asks no follow-up question after it.

Length1 <= length <= 5000

record_call?boolean

speed?number

Voice playback rate multiplier. Some voices only support 0.8–1.2; out-of-range values for such voices return 400.

Range0.7 <= value <= 1.2

tts_style_level?number

Voice style level from 0 (calm) to 1 (expressive). Omit to use 0.5.

Multiple Of0.01

Range0 <= value <= 1

background_ambience?string

Background ambience bed mixed under the assistant voice during phone calls. Omit to use clean (no bed).

Value in

"clean"
"office"
"restaurant"

appointment_booking_enabled?boolean

contextual_asr_correction_enabled?boolean

Per-turn LLM correction of misrecognised proper nouns (names, companies, products) in caller transcripts, using the assistant's own contacts, employees, glossary and knowledge. Adds latency on turns that carry a candidate. Default false.

allow_preferred_language?boolean

whitelist?boolean

prompt_id?|

Match^[a-f0-9]{24}$

email_prompt_id?|

Match^[a-f0-9]{24}$

knowledge_group_ids?array<>

Default[]

glossary_group_ids?array<>

Default[]

pronunciation_group_ids?array<>

Default[]

forwarding_group_ids?array<>

Default[]

contact_group_ids?array<>

Default[]

calendar_ids?array<>

Itemsitems <= 1

Default[]

tool_ids?array<>

Default[]

analysis_ids?array<>

Default[]

pre_call_webhook?|

Optional lookup that supplies caller context from your endpoint at the start of inbound and outbound calls. Add @preCallData to the assistant's assigned prompt to use the response. Saving this object does not call the endpoint or edit the prompt.

Every supplied object requires enabled. When true, include a nonempty HTTPS url in the same request, even if a URL is already stored. String input limits count Unicode characters.

On creation or first configuration, omitted fields default to POST, empty headers and body template, no authentication, and a 5000 ms timeout. Omit pre_call_webhook or send null on creation to leave it unconfigured.

On PATCH, omit pre_call_webhook to preserve it, or send null to remove the configuration and credentials. A supplied object merges with the stored configuration; omitted nested fields retain their values, except that changing url requires the stored credential again (see auth). { "enabled": false } disables execution while retaining the configuration and credentials. See headers and auth for their replacement rules. Enterprise assistants support the same webhook updates. A concurrent clear, auth-state change, or URL change of a webhook with a stored credential can return 409 without applying any part of the PATCH; fetch the latest assistant before retrying.

The endpoint must return a successful (2xx) response containing JSON or text, up to 256 KiB. JSON is serialized to text for @preCallData; the injected text is limited to 4000 characters. Execution runs in the background without retries. Disabled, failed, timed-out or busy requests contribute an empty value. Prompt rendering waits at most 400 ms once per call; a later response can be used on later turns.

Response Body

`application/json`

curl -X POST "https://example.com/assistants" \  -H "Content-Type: application/json" \  -d '{    "name": "Sarah",    "language": "de",    "voice_id": "cgSgspJ2msm6clMCkdW9",    "company_name": "Example GmbH",    "company_industry": "Logistics",    "introduction": "Hello, how can I help you today?"  }'

{  "data": {    "id": "string",    "name": "string",    "description": "string",    "language": "de",    "voice_id": "string",    "record_call": true,    "speed": 0.7,    "tts_style_level": 0,    "background_ambience": "clean",    "appointment_booking_enabled": true,    "contextual_asr_correction_enabled": true,    "allow_preferred_language": true,    "whitelist": true,    "introduction": "string",    "company_name": "string",    "company_industry": "string",    "phone_number": "string",    "carrier": "string",    "prompt_id": "string",    "email_prompt_id": "string",    "knowledge_group_ids": [      "string"    ],    "glossary_group_ids": [      "string"    ],    "pronunciation_group_ids": [      "string"    ],    "forwarding_group_ids": [      "string"    ],    "contact_group_ids": [      "string"    ],    "calendar_ids": [      "string"    ],    "tool_ids": [      "string"    ],    "analysis_ids": [      "string"    ],    "pre_call_webhook": {      "enabled": true,      "url": "string",      "method": "GET",      "headers": {        "property1": "string",        "property2": "string"      },      "body_template": "string",      "timeout_ms": 500,      "auth": {        "type": "none",        "header_name": "string",        "username": "string"      }    },    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  }}

Create an assistant

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`