Callmatic API Documentation

Programmatically trigger and manage voicebot-powered outbound calls, retrieve transcripts, and access recordings.

API Setup Guide

The Callmatic API allows you to programmatically trigger and manage voicebot-powered outbound calls. You can initiate single or batch calls, retrieve call details and transcripts, and access call recordings. To run the APIs, you need an apiKey and a campaignId.

1. Generate API Key

Sign up or log in at the Callmatic Admin Portal.
Once logged in, click on the Profile Icon in the top-right corner.
From the dropdown menu, select Account Section.
In the Account Section, click on Generate API Key.
Copy the generated API key and save it in a secure location for future use.

2. Get Campaign ID

Go to the Campaign List Page.
Click on the relevant campaign you want to work with.
Copy the Campaign ID from the URL in your browser's address bar.

You now have both the apiKey and campaignId required to run the APIs.

Authentication

All API requests must include an API key in the header:

api-key: {{your_api_key}}

Base URL

https://api.callmatic.ai/v1

Endpoints

1. Trigger a Single Call

POST/calls

Initiates a call to one recipient.

Headers

Content-Type: application/json
api-key: {{your_api_key}}

Request Body Example

{
  "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
  "phoneNumber": "7760524807",
  "variables": {
    "name": "Shivank"
  }
}

Response Example

{
  "success": true,
  "data": {
    "callId": "e08bad66-ee60-458d-958f-a02b1f12d355",
    "phoneNumber": "7760524807",
    "variables": {
      "name": "Shivank"
    },
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb"
  }
}

2. Trigger Batch Calls

POST/calls/batch

Initiates multiple calls under a single campaign.

Headers

Content-Type: application/json
api-key: {{your_api_key}}

Request Body Example

{
  "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
  "to": [
    {
      "phoneNumber": "7760524807",
      "variables": {
        "name": "Shivank"
      }
    }
  ]
}

Response Example

{
  "success": true,
  "data": {
    "calls": [
      {
        "callId": "e08bad66-ee60-458d-958f-a02b1f12d355",
        "phoneNumber": "7760524807",
        "variables": {
          "name": "Shivank"
        }
      }
    ],
    "duplicates": 0,
    "enqued": 1,
    "status": "ACTIVE",
    "triggered": false,
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb"
  },
  "message": "Call triggered successfully"
}

You can include a maximum of 200 calls in a single API request.

3. Get Call Status & Details

GET/calls/{callId}

Retrieve metadata, status, transcript, and insights of a call.

Headers

Content-Type: application/json
api-key: {{your_api_key}}

Sample Request

curl --location 'https://api.callmatic.ai/v1/calls/e08bad66-ee60-458d-958f-a02b1f12d355' \
--header 'Content-Type: application/json' \
--header 'api-key: {{your_api_key}}'

Response Example (truncated)

{
  "success": true,
  "data": {
    "callId": "e08bad66-ee60-458d-958f-a02b1f12d355",
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
    "direction": "OUTBOUND",
    "phoneNumber": "7347087599",
    "status": "completed",
    "triggeredAt": "2025-08-29T14:13:36.294Z",
    "startTime": "2025-08-29T14:13:46.772Z",
    "endTime": "2025-08-29T14:14:06.000Z",
    "duration": 19.18,
    "transcript": [
      {
        "sender": "bot",
        "timestamp": 1756476827.0507,
        "text": "नमस्ते, मैं राधा बोल रही हूँ, XYZ से..."
      },
      {
        "sender": "human",
        "timestamp": 1756476833.4055,
        "text": " Yes."
      }
    ],
    "insights": [
      {
        "actionType": "SUMMARIZE",
        "output": {
          "summary": "आशु जी का 706 रुपये का लोन भुगतान बकाया है..."
        }
      }
    ]
  }
}

4. Get Call Recording

GET/recordings/{callId}

Fetch the audio recording of a call.

Headers

api-key: {{your_api_key}}

Sample Request

curl --location --globoff 'https://api.callmatic.ai/v1/recordings/{{CallId}}' \
--header 'api-key: {{your_api_key}}'

Returns the audio file stream (format may vary depending on configuration).

Error Handling

Errors return JSON with an HTTP status code.

Example

{
  "success": false,
  "error": "Invalid API key"
}

Webhook Callback Notification

After a call is completed—whether successful or failed—our system will send a POST request to your configured webhook URL.

Request body

{
  "callId": "e08bad66-ee60-458d-958f-a02b1f12d355",
  "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
  "direction": "OUTBOUND",
  "phoneNumber": "7347087599",
  "status": "completed",
  "triggeredAt": "2025-08-29T14:13:36.294Z",
  "startTime": "2025-08-29T14:13:46.772Z",
  "endTime": "2025-08-29T14:14:06.000Z",
  "duration": 19.18,
  "transcript": [
    {
      "sender": "bot",
      "timestamp": 1756476827.0507,
      "text": "नमस्ते, मैं राधा बोल रही हूँ, XYZ से..."
    },
    {
      "sender": "human",
      "timestamp": 1756476833.4055,
      "text": " Yes."
    }
  ],
  "insights": [
    {
      "actionType": "SUMMARIZE",
      "output": {
        "summary": "आशु जी का 706 रुपये का लोन भुगतान बकाया है..."
      }
    }
  ]
}

Back to home

Need any help? We are just a WhatsApp message away.