Skip to Content
WalidoDocs
Public APIAssistants

Create an assistant

POST
/assistants

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. Organizations that route calls through their own assigned carrier must send phone_number_id; the platform does not allocate a number for them, and a request without it returns 400 validation_failed. While the organization's first assistant is still being set up, or when its assigned carrier is no longer available, the request returns 409 conflict. Cross-resource refs (prompt_id, knowledge_group_ids, etc.) are validated to belong to your organization before the assistant is saved.

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Request Body

application/json
  1. body
phone_number_id?string

A purchased number from GET /phone-numbers. Omit it to have the platform allocate a number; organizations that route calls through their own assigned carrier must send it. 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

Assistant language.

Value in"de""en""fr""it""de-CH""es""pt""tr""sv""fi""nl"
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 greeting in the assistant's language. Translations into the other supported languages are generated in the background. 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}$
outbound_prompt_id?|

Prompt for outbound calls. null (the default) means outbound calls use 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<>

Call analyses to run on this assistant's calls. An analysis whose flow contains the delete-call node deletes each call it runs on, so listing one requires the API key's role to grant call_logs.call_data delete; in recording mode the node deletes only each call's recording and requires call_logs.call_recording delete instead. One whose flow contains the start-call node places an outbound call after each call it runs on, so listing one requires assistants.triggerOutbound post. Otherwise the request returns 403 forbidden and no assistant is created. An MCP connection never attaches an analysis with the start-call node.

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. 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

Created.

application/json
  1. response
data?
Example Request
curl -X POST 'https://api.walido.it/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?"}'
Example Response
{  "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",    "outbound_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"  }}