Trigger Test Call

Trigger outbound test call

curl --request POST \
  --url https://api.inya.ai/platform/v1/agents/{botId}/trigger_call \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "phone": "9876543210",
  "countryCode": "+91",
  "name": "Jane Doe"
}
'

import requests

url = "https://api.inya.ai/platform/v1/agents/{botId}/trigger_call"

payload = {
    "phone": "9876543210",
    "countryCode": "+91",
    "name": "Jane Doe"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({phone: '9876543210', countryCode: '+91', name: 'Jane Doe'})
};

fetch('https://api.inya.ai/platform/v1/agents/{botId}/trigger_call', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "status": "success",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Call is being triggered to 9876543210",
  "response": {
    "clientReferenceId": "my-ref-001"
  }
}

{
  "status": "error",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "<string>"
}

{
  "status": "error",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "<string>"
}

{
  "status": "error",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "<string>"
}

POST

agents

{botId}

trigger_call

Trigger outbound test call

curl --request POST \
  --url https://api.inya.ai/platform/v1/agents/{botId}/trigger_call \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "phone": "9876543210",
  "countryCode": "+91",
  "name": "Jane Doe"
}
'

import requests

url = "https://api.inya.ai/platform/v1/agents/{botId}/trigger_call"

payload = {
    "phone": "9876543210",
    "countryCode": "+91",
    "name": "Jane Doe"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({phone: '9876543210', countryCode: '+91', name: 'Jane Doe'})
};

fetch('https://api.inya.ai/platform/v1/agents/{botId}/trigger_call', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "status": "success",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Call is being triggered to 9876543210",
  "response": {
    "clientReferenceId": "my-ref-001"
  }
}

{
  "status": "error",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "<string>"
}

{
  "status": "error",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "<string>"
}

{
  "status": "error",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "<string>"
}

Overview

Trigger an outbound test call from a voice agent. The agent will call the specified phone number and conduct a conversation based on its current configuration. This endpoint is primarily used for testing and validation purposes.

Required Permission

agents

Path Parameters

Name	Type	Required	Description
`botId`	string	Yes	Unique agent identifier.

Query Parameters

Name	Type	Required	Description
`environment`	string	No	Target environment: `development`, `staging`, or `production`. Defaults to `development`.

For some API key types (e.g. Developer role), environment=development must be passed explicitly. Omitting it will return a 403 error: "Developer can only trigger calls in the development environment". If you receive this error, add ?environment=development to your request.

Outbound calls can only be placed to phone numbers that have been pre-registered (whitelisted) for your organization. Attempting to call an unregistered number returns HTTP 400. Contact your Inya account manager to register numbers for outbound calling.

Request Body

Field	Type	Required	Description
`phone`	string	Yes	Phone number to call, without the country code.
`countryCode`	string	Yes	Country dialing code, including the `+` prefix (e.g. `+91`, `+1`).
`name`	string	Yes	Name of the person being called.
`clientReferenceId`	string	No	A client-supplied reference ID that you define. See details below.

`clientReferenceId` Field

clientReferenceId is an optional free-form string that lets you link the Inya call record to your own system’s data (e.g. a CRM lead ID, booking reference, or campaign code). When provided:

It is stored against the conversation record in the Inya platform.
It is forwarded to the Dynamic Greeting API webhook (if hasDynamicGreeting is true), allowing your server to personalize the opening message.
It is returned in the response under response.clientReferenceId.

When clientReferenceId is omitted, the response field in the success payload will be null.

Example cURL

curl -X POST "https://api.inya.ai/platform/v1/agents/fb79920229d144608ebf665a10e50275/trigger_call?environment=development" \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "9876543210",
    "countryCode": "+91",
    "name": "Jane Doe",
    "clientReferenceId": "crm-lead-42"
  }'

Response

Success (200) — with `clientReferenceId`

{
  "status": "success",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Call is being triggered to 9876543210",
  "response": {
    "clientReferenceId": "crm-lead-42"
  }
}

Success (200) — without `clientReferenceId`

{
  "status": "success",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Call is being triggered to 9876543210",
  "response": null
}

Error Responses

400 Bad Request - Invalid phone number or parameters

{
  "status": "failure",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Phone number provided is Invalid"
}

400 Bad Request - Phone number not whitelisted for outbound calls

{
  "status": "failure",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Phone number is not registered for outbound calls"
}

403 Forbidden - Insufficient permissions

{
  "status": "failure",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "User does not have permission to trigger Test calls"
}

403 Forbidden - Agent not found or not accessible

{
  "status": "failure",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "User does not have access to this bot"
}

Use Cases

Testing a new agent configuration against a real phone call
Validating dynamic greeting responses before a production campaign
Triggering calls with a reference ID to track conversations against your own records
Verifying voicemail detection and call transfer behaviour

Ensure you have proper consent and comply with local telecommunications regulations before triggering outbound calls. Do not use this endpoint in production for large-scale campaigns.

Use the environment query parameter to direct test calls to your development configuration, keeping production traffic clean.

Save the requestId from every response. You will need it if you contact Inya support to trace a specific request.

Authorizations

x-api-key

string

header

required

API key with 'agents' permission

Path Parameters

botId

string

required

Unique identifier of the agent

Query Parameters

environment

enum<string>

Target environment

Available options:

development,

staging,

production

Body

application/json

phone

string

required

Example:

"9876543210"

countryCode

string

required

Example:

"+91"

name

string

required

Example:

"Jane Doe"

clientReferenceId

string

Optional client-supplied reference ID. Stored against the conversation and forwarded to the dynamic greeting API.

Example:

"my-ref-001"

Response

Call triggered successfully

status

string

Example:

"success"

requestId

string

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

message

string

response

object

Getting Started

Agents API

Conversations API

Agent Config API

Agent FAQ API

Chat SDK API

Reference

Overview

Required Permission

Path Parameters

Query Parameters

Request Body

`clientReferenceId` Field

Example cURL

Response

Success (200) — with `clientReferenceId`

Success (200) — without `clientReferenceId`

Error Responses

Use Cases

Authorizations

Path Parameters

Query Parameters

Body

Response

​Overview

​Required Permission

​Path Parameters

​Query Parameters

​Request Body

​clientReferenceId Field

​Example cURL

​Response

​Success (200) — with clientReferenceId

​Success (200) — without clientReferenceId

​Error Responses

​Use Cases

Authorizations

Path Parameters

Query Parameters

Body

Response

Overview

Required Permission

Path Parameters

Query Parameters

Request Body

`clientReferenceId` Field

Example cURL

Response

Success (200) — with `clientReferenceId`

Success (200) — without `clientReferenceId`

Error Responses

Use Cases