> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gnani.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Test Call

> Initiate an outbound test call using the specified agent

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

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

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

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

```bash theme={null}
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`

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

### Success (200) — without `clientReferenceId`

```json theme={null}
{
  "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

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

**400 Bad Request** - Phone number not whitelisted for outbound calls

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

**403 Forbidden** - Insufficient permissions

```json theme={null}
{
  "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

```json theme={null}
{
  "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

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

<Tip>
  Use the `environment` query parameter to direct test calls to your development configuration, keeping production traffic clean.
</Tip>

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


## OpenAPI

````yaml POST /v1/agents/{botId}/trigger_call
openapi: 3.0.3
info:
  title: Platform Agents API
  description: API endpoints for creating, managing, and interacting with voice agents
  version: 2.1.0
servers:
  - url: https://api.inya.ai/platform
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Agents
    description: Agent management operations
  - name: AgentFAQ
    description: Agent FAQ management
  - name: AgentCallTriggers
    description: Outbound call triggers
  - name: ChatSDK
    description: Chat Widget configuration
  - name: Conversations
    description: Conversation logs, statistics, and audio
paths:
  /v1/agents/{botId}/trigger_call:
    post:
      tags:
        - AgentCallTriggers
      summary: Trigger outbound test call
      description: >-
        Initiate an outbound test call to the specified phone number using the
        given agent.
      operationId: triggerCall
      parameters:
        - $ref: '#/components/parameters/AgentId'
        - name: environment
          in: query
          description: Target environment
          required: false
          schema:
            type: string
            enum:
              - development
              - staging
              - production
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerCallRequest'
            examples:
              indiaCall:
                value:
                  phone: '9876543210'
                  countryCode: '+91'
                  name: Jane Doe
                  clientReferenceId: my-ref-001
      responses:
        '200':
          description: Call triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  value:
                    status: success
                    requestId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: Call is being triggered to 9876543210
                    response:
                      clientReferenceId: my-ref-001
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    AgentId:
      name: botId
      in: path
      required: true
      description: Unique identifier of the agent
      schema:
        type: string
  schemas:
    TriggerCallRequest:
      type: object
      required:
        - phone
        - countryCode
        - name
      properties:
        phone:
          type: string
          example: '9876543210'
        countryCode:
          type: string
          example: '+91'
        name:
          type: string
          example: Jane Doe
        clientReferenceId:
          type: string
          example: my-ref-001
          description: >-
            Optional client-supplied reference ID. Stored against the
            conversation and forwarded to the dynamic greeting API.
    StandardResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        requestId:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        message:
          type: string
        response:
          type: object
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        requestId:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        message:
          type: string
  responses:
    BadRequest:
      description: Validation error or malformed request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Permission denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key with 'agents' permission

````