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.
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.
bearerAuthAuthorizationBearer <token>API key in the Authorization: Bearer <key> header.
Keys are created in the Hallolara dashboard (Settings → API Keys).
application/json- body
phone_number_id?stringA 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.
^[a-fA-F0-9]{24}$name*string1 <= length <= 100description?stringlength <= 500""language*stringAssistant language.
"de""en""fr""it""de-CH""es""pt""tr""sv""fi""nl"voice_id*stringVoice ID. Must be one of the values returned by GET /voices; an unknown or unavailable ID returns 400.
company_name*string1 <= length <= 200company_industry*string1 <= length <= 200introduction*stringOpening 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.
1 <= length <= 5000record_call?booleanspeed?numberVoice playback rate multiplier. Some voices only support 0.8–1.2; out-of-range values for such voices return 400.
0.7 <= value <= 1.2tts_style_level?numberVoice style level from 0 (calm) to 1 (expressive). Omit to use 0.5.
0.010 <= value <= 1background_ambience?stringBackground ambience bed mixed under the assistant voice during phone calls. Omit to use clean (no bed).
"clean""office""restaurant"appointment_booking_enabled?booleancontextual_asr_correction_enabled?booleanPer-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?booleanwhitelist?booleanprompt_id?|^[a-f0-9]{24}$outbound_prompt_id?|Prompt for outbound calls. null (the default) means outbound calls use prompt_id.
^[a-f0-9]{24}$knowledge_group_ids?array<>[]glossary_group_ids?array<>[]pronunciation_group_ids?array<>[]forwarding_group_ids?array<>[]contact_group_ids?array<>[]calendar_ids?array<>items <= 1[]tool_ids?array<>[]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.
[]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.
Created.
application/json- response
data?curl -X POST 'https://api.hallolara.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?"}'{ "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" }}