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": "failure",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "<string>"
}

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

{
  "status": "failure",
  "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": "failure",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "<string>"
}

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

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

What it does: Tells an agent to call a phone number. The agent runs a live conversation using its current configuration.

PUT  /v1/agents/{botId}              → configure agent
POST /v1/agents/{botId}/trigger_call → place the call     (this page)
POST /v1/conversations/logs          → find conversationId
GET  /v1/conversations/{id}/stats   → read disposition + transcript

Or skip steps 3–4: enable a post-call webhook and receive call data automatically when the call ends.

Required Permission

agents

Minimum working example

Always pass ?environment=development unless your API key has production access.

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"
  }'

Path and query parameters

Name	Location	Required	Description
`botId`	Path	Yes	Agent to place the call from. Get it from List Agents or Create Agent.
`environment`	Query	Often yes	`development`, `staging`, or `production`. Omitting this may return `403` for Developer-role keys.

Outbound calls only work to whitelisted phone numbers. Calling an unregistered number returns HTTP 400. Contact your account manager to register numbers.

Request body

Field	Required	Description
`phone`	Yes	Phone number without country code — e.g. `"9876543210"`.
`countryCode`	Yes	Dialing code with `+` prefix — e.g. `"+91"`.
`name`	Yes	Label for the person being called. Appears in conversation logs as `name`.
`clientReferenceId`	No	Your CRM or campaign ID. Links the call to your system. See below.

`clientReferenceId`

Optional free-form string to tie the call back to your records (CRM lead ID, booking reference, campaign code). When provided:

Stored on the conversation record
Forwarded to the dynamic greeting API if hasDynamicGreeting is enabled
Returned in the trigger response under response.clientReferenceId
May appear in post-call webhook payloads

When omitted, response is null on success.

Response

Success (200) — with `clientReferenceId`

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

Success (200) — without `clientReferenceId`

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

A 200 response means the call is being placed — not that it has finished. Use Get Conversation Logs or a post-call webhook to read the outcome after the call ends.

What happens after you trigger

Trigger Call (200)
      │
      ▼
Agent dials the number
      │
      ├─ Phone not whitelisted        → 400 at trigger time
      ├─ Dynamic greeting API fails   → 400 at trigger time
      ├─ Callee does not answer       → callStatus: "NO ANSWER" in Stats
      └─ Call connects                → utteranceAnalytics + overallCallDisposition in Stats
                                              (or post-call webhook fires)

Edge cases

Scenario	What happens
Missing `?environment=development`	HTTP `403` — `"Developer can only trigger calls in the development environment"`
Phone not whitelisted	HTTP `400` — `"Phone number is not registered for outbound calls"`
Invalid phone format	HTTP `400` — `"Phone number provided is Invalid"`
Dynamic greeting or pre-call API misconfigured	HTTP `400` — check your Update Agent `dynamicInitialMessageConfig` and `preCall` settings
Agent not accessible	HTTP `403` — wrong `botId` or insufficient permissions

Errors

403 Forbidden — missing environment

{
  "status": "failure",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Developer can only trigger calls in the development environment"
}

400 Bad Request — phone not whitelisted

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

400 Bad Request — dynamic greeting / pre-call failure

{
  "status": "failure",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Please check your dynamic greeting message API or precall/dynamic variables and try again"
}

Ensure you have proper consent and comply with local telecommunications regulations before triggering outbound calls. This endpoint is for testing — not large-scale production campaigns.

Save the requestId from every response. You will need it if you contact Gnani 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

Required Permission

Minimum working example

Path and query parameters

Request body

`clientReferenceId`

Response

Success (200) — with `clientReferenceId`

Success (200) — without `clientReferenceId`

What happens after you trigger

Edge cases

Errors

Authorizations

Path Parameters

Query Parameters

Body

Response

​Required Permission

​Minimum working example

​Path and query parameters

​Request body

​clientReferenceId

​Response

​Success (200) — with clientReferenceId

​Success (200) — without clientReferenceId

​What happens after you trigger

​Edge cases

​Errors

Authorizations

Path Parameters

Query Parameters

Body

Response

Required Permission

Minimum working example

Path and query parameters

Request body

`clientReferenceId`

Response

Success (200) — with `clientReferenceId`

Success (200) — without `clientReferenceId`

What happens after you trigger

Edge cases

Errors