Service Agent

Create an aicall

Changed on

Creates a new AI call for the service agent's customer and returns the created aicall's details. An activeflow is automatically created and associated with the new AI call. reference_type must be one of call, conversation, contact_case, or an empty string (no reference; reference_id is then ignored). For the other types the referenced resource must belong to the caller's customer. An unsupported reference_type returns 400; a reference that does not exist or does not belong to the caller's customer returns 404.

post/service_agents/aicalls

Request

  • Base URL
    https://api.voipbin.net/v1.0
  • URL
    https://api.voipbin.net/v1.0/service_agents/aicalls
  • Auth
    none declared

Request body

assistance_type'' | 'ai' | 'team' required

Type of assistance entity associated with the AI call.

assistance_idstring uuid

The unique identifier of the assistance entity (AI or Team). Returned from the POST /ais, GET /ais, POST /teams, or GET /teams response. Optional when assistance_type=ai and reference_type=contact_case: if omitted, the customer's own type=insight AI is resolved automatically. Required for every other combination.

reference_type'' | 'call' | 'conversation' | 'task' | 'contact_case' required

Type of reference associated with the ai call.

reference_idstring uuid required

The ID of the reference resource for the AI call.

Example request

{
  "assistance_type": "ai",
  "assistance_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_type": "call",
  "reference_id": "5e4a0680-804e-11ec-8477-2fea5968d85b"
}

Response

The created aicall details.

idstring uuid

The unique identifier of the AI call.

customer_idstring uuid

The unique identifier of the associated customer. Returned from the GET /customers response.

assistance_type'' | 'ai' | 'team'

Type of assistance entity associated with the AI call.

assistance_idstring uuid

The unique identifier of the assistance entity (AI or Team). Returned from the POST /ais, GET /ais, POST /teams, or GET /teams response.

ai_engine_modelstring

Model of the AI engine. Uses target.model format (e.g., openai.gpt-5). The target prefix identifies the provider, and the model name follows after the dot. The list of selectable models is returned by GET /ai_models. A value in the form openrouter.<author>/<slug> is also accepted (custom OpenRouter model, see model_id_prefix in GET /ai_models); in that case engine_key is required. A value in the form customendpoint.<model-id> selects an OpenAI-compatible server that you host; in that case engine_base_url is required and engine_base_key is optional. The customendpoint. model is not listed in GET /ai_models.

ai_tts_type'' | 'async' | 'aws' | 'azure' | 'cartesia' | 'deepgram' | 'elevenlabs' | 'fish' | 'google' | 'groq' | 'hume' | 'inworld' | 'lmnt' | 'minimax' | 'neuphonic' | 'nvidia-riva' | 'openai' | 'piper' | 'playht' | 'rime' | 'sarvam' | 'xtts'

Text-to-speech provider type.

ai_tts_voice_idstring

Text-to-speech voice identifier used for this call.

ai_stt_type'' | 'cartesia' | 'deepgram' | 'elevenlabs'

Speech-to-text provider type.

ai_smart_turn_enabledboolean

Smart turn detection setting frozen from the AI configuration at call start.

parameterobject

Merged key-value parameter data from AI and team configuration.

activeflow_idstring uuid

The unique identifier of the activeflow. Returned from the GET /activeflows response.

reference_type'' | 'call' | 'conversation' | 'task' | 'contact_case'

Type of reference associated with the ai call.

reference_idstring uuid

The unique identifier of the referenced resource. The actual resource type is determined by reference_type. Returned from the corresponding resource endpoint.

confbridge_idstring uuid

The unique identifier of the conference bridge. Returned from the GET /conferences response.

current_member_idstring uuid

The unique identifier of the currently active team member. Only set when assistance_type is 'team'. Updated when the AI agent transitions to a different team member.

status'initiating' | 'progressing' | 'pausing' | 'resuming' | 'terminating' | 'terminated'

Status of the ai call.

stt_languagestring

STT language copied from AI config at creation time.

metadataobject

Generic key-value store. Contains prompt_snapshots (array of PromptSnapshot) at call start time.

tm_endstring date-time

Timestamp when the AI call ended.

tm_createstring date-time

Timestamp when the AI call was created.

tm_updatestring date-time

Timestamp when the AI call was last updated.

tm_deletestring date-time

Timestamp when the AI call was deleted.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "7c4d2f3a-1b8e-4f5c-9a6d-3e2f1a0b4c5d",
  "assistance_type": "ai",
  "assistance_id": "550e8400-e29b-41d4-a716-446655440000",
  "ai_engine_model": "openai.gpt-5",
  "ai_tts_type": "elevenlabs",
  "ai_tts_voice_id": "21m00Tcm4TlvDq8ikWAM",
  "ai_stt_type": "deepgram",
  "ai_vad_config": {
    "confidence": 0.7,
    "start_secs": 0.2,
    "stop_secs": 0.5,
    "min_volume": 0.6
  },
  "parameter": {
    "language": "en-US",
    "department": "support"
  },
  "activeflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_type": "call",
  "reference_id": "550e8400-e29b-41d4-a716-446655440000",
  "confbridge_id": "550e8400-e29b-41d4-a716-446655440000",
  "current_member_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "progressing",
  "stt_language": "en-US",
  "tm_end": "2026-01-15T09:30:00.000000Z",
  "tm_create": "2026-01-15T09:30:00.000000Z",
  "tm_update": "2026-01-15T09:30:00.000000Z",
  "tm_delete": "2026-01-15T09:30:00.000000Z"
}

Changes

  • eac9c21954d6Revision changes
    • info

      added the non-success response with the status

  • bd02a69a591dRevision changes
    • info

      removed the gemini.gemini-2.0-flash enum value from the response property for the response status

    • info

      removed the gemini.gemini-2.5-flash enum value from the response property for the response status

    • info

      removed the gemini.gemini-2.5-pro enum value from the response property for the response status

    • info

      removed the gemini.gemini-pro-latest enum value from the response property for the response status

    • info

      removed the grok.grok-3 enum value from the response property for the response status

    • info

      removed the grok.grok-3-mini enum value from the response property for the response status

    • info

      removed the openai.gpt-5 enum value from the response property for the response status

    • info

      removed the openai.gpt-5-mini enum value from the response property for the response status

    • info

      removed the openai.gpt-5-nano enum value from the response property for the response status

    • info

      removed the openai.gpt-5.1 enum value from the response property for the response status

    • info

      removed the openai.gpt-5.2 enum value from the response property for the response status