Quick Start

The Twenty2 API lets you integrate AI voice calling directly into your own systems and workflows without using the Twenty2 dashboard.

This guide walks you through triggering your first outbound call and retrieving its result using the API.

What you can do

All API requests are made to:

https://api.twentytwo.in/api

How the API works

When you trigger a call via the API, the request is non-blocking. The endpoint immediately returns a call_id after the call is queued, while the actual phone call is placed asynchronously.

Use the returned call_id to track the call and retrieve results once it completes.

POST /agent/trigger-outbound-call  →  returns call_id
GET  /call/detail?call_id=...      →  returns call result, transcript, and output parameters

Calls are placed only between 9:00 AM and 9:00 PM IST. Calls triggered outside this window are automatically queued and initiated at 9:00 AM the next day.

Before you begin

Make sure you have:

• A Twenty2 account at https://app.twentytwo.in

• A published AI assistant from My Assistants

• A phone number purchased under Manage Numbers

• Sufficient wallet balance under Billing → Add Balance

Step 1: Get your API credentials

Generate an API Key and Secret from:

Profile → Integrations → Build with Twenty2 API → Create New

Create your Basic Authentication token:

echo -n "your_api_key:your_api_key_secret" | base64

See the Authentication page for complete details.

Step 2: Get your IDs

Assistant ID: Go to My Assistants, click the three-dot menu on your published assistant, and select Copy Assistant ID.

Workspace ID: Click the copy icon next to Switch Workspace at the bottom-left of the platform.

Caller phone: The number you purchased under Manage Numbers.

Step 3: Trigger your first call

curl -X POST "https://api.twentytwo.in/api/agent/trigger-outbound-call" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64(api_key:api_key_secret)>" \
  -d '{
    "assistant_id": "<your_assistant_id>",
    "callee_phone": "9999999999",
    "caller_phone": "<your_caller_phone>",
    "input_parameters": {
      "customerName": "Rohit"
    }
  }'

Successful requests return a call_id:

{
  "success": true,
  "statusCode": 201,
  "data": {
    "call_id": "6a329e7c5a54529ba7f0b4e6",
    "message": "Call queued successfully."
  }
}

Step 4: Retrieve the call result

After the call completes, use the call_id to fetch the complete call details.

curl -X GET "https://api.twentytwo.in/api/call/detail?call_id=6a329e7c5a54529ba7f0b4e6" \
  -H "Authorization: Basic <base64(api_key:api_key_secret)>" \
  -H "x-workspace-id: <your_workspace_id>"

The response includes:

• Call status

• Duration

• Call cost

• Captured output parameters

• Recording URL

• Transcript URL

{
  "success": true,
  "call": {
    "call_id": "6a329e7c5a54529ba7f0b4e6",
    "status": "completed",
    "duration_seconds": 94,
    "cost": "₹15.67",
    "output_parameters": {
      "interested": "yes",
      "callback_requested": "yes",
      "callback_time": "Tomorrow 11am"
    },
    "recording": {
      "url": "https://storage.twentytwo.in/recordings/...",
      "expires_at": "2025-01-25T10:01:34Z"
    }
  }
}

You have now successfully triggered an AI voice call and retrieved its results using the Twenty2 API.