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. Cross-resource refs (prompt_id, knowledge_group_ids, etc.) are validated to belong to your organization before the assistant is saved.

Optionally configure pre_call_webhook in this initial request. Configuration and credentials are validated and encrypted before assistant creation begins; saving does not call the webhook. Add @preCallData to the assigned prompt to use the lookup response. See the pre-call webhook schema for template variables and runtime limits.

Authorization

AuthorizationBearer <token>

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

In: header

Request Body

namestring

Length1 <= length <= 100

description?string

Default""

Lengthlength <= 500

languagestring

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

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

voice_idstring

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

company_namestring

Length1 <= length <= 200

company_industrystring

Length1 <= length <= 200

introductionstring

Opening text in the assistant language. The platform stores it as the canonical original localized introduction and generates other supported-language variants asynchronously.

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"

interruptable?boolean

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?string|null

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

email_prompt_id?string|null

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

knowledge_group_ids?array<string>

Default[]

glossary_group_ids?array<string>

Default[]

pronunciation_group_ids?array<string>

Default[]

forwarding_group_ids?array<string>

Default[]

contact_group_ids?array<string>

Default[]

calendar_ids?array<string>

Default[]

Itemsitems <= 1

tool_ids?array<string>

Default[]

analysis_ids?array<string>

Default[]

pre_call_webhook?object|null

Null clears the configuration. A supplied object requires enabled and, when enabled, a nonempty HTTPS url. Any supplied nonempty url must be valid HTTPS even when disabled; disabled configurations also accept null or an empty string. A host is required, ports must be numeric, and percent escapes must contain two hexadecimal digits. String length limits count Unicode characters. Other omitted fields preserve their values on PATCH. Initial defaults are POST, empty headers/body template, no authentication and 5000 ms. See PreCallWebhook for runtime behavior.

Response Body

application/json

curl -X POST "https://api.smao.ai/api/v1/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?",
    "pre_call_webhook": {
      "enabled": true,
      "url": "https://crm.example.com/lookup",
      "auth": {
        "type": "bearer",
        "secret": "example-only-token"
      }
    }
  }'

curl -X POST "https://api.smao.ai/api/v1/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?",    "pre_call_webhook": {      "enabled": true,      "url": "https://crm.example.com/lookup",      "auth": {        "type": "bearer",        "secret": "example-only-token"      }    }  }'

{
  "data": {
    "id": "65f8fa6f1a9d8e0012ab34cd",
    "name": "Sarah",
    "description": "Receptionist assistant for inbound calls.",
    "language": "de",
    "voice_id": "cgSgspJ2msm6clMCkdW9",
    "record_call": true,
    "speed": 0.7,
    "tts_style_level": 1,
    "background_ambience": "clean",
    "interruptable": true,
    "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": "+491701234567",
    "carrier": "string",
    "prompt_id": "65a1234567890abcdef01234",
    "email_prompt_id": "65a1234567890abcdef05678",
    "knowledge_group_ids": [
      "65a1234567890abcdef01234"
    ],
    "glossary_group_ids": [
      "65a1234567890abcdef01234"
    ],
    "pronunciation_group_ids": [
      "65a1234567890abcdef01234"
    ],
    "forwarding_group_ids": [
      "65a1234567890abcdef01234"
    ],
    "contact_group_ids": [
      "65a1234567890abcdef01234"
    ],
    "calendar_ids": [
      "65a1234567890abcdef01234"
    ],
    "tool_ids": [
      "65a1234567890abcdef01234"
    ],
    "analysis_ids": [
      "65a1234567890abcdef01234"
    ],
    "pre_call_webhook": {
      "enabled": true,
      "url": "https://crm.example.com/lookup",
      "method": "POST",
      "headers": {
        "X-Caller": "@callerNumber"
      },
      "body_template": "{\"caller\":\"@callerNumber\",\"session\":\"@sessionId\"}",
      "timeout_ms": 5000,
      "auth": {
        "type": "bearer"
      }
    },
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing API key"
  }
}

{
  "error": {
    "code": "subscription_required",
    "message": "This feature is not available in your current subscription. Please upgrade to a higher plan"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "No permission"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Not found"
  }
}

{
  "error": {
    "code": "conflict",
    "message": "Group is assigned to an assistant"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred."
  }
}

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