# Click to Call API

## Endpoint Description

<mark style="color:green;">`POST`</mark> [`https://outgoing-call.alohaa.ai/v1/external/click-2-call`](https://outgoing-call.alohaa.ai/v1/external/click-2-call)

## Parameters

#### Request Headers

<table><thead><tr><th width="176">Field</th><th width="217">Value</th><th width="241">Description</th><th>Mandatory</th></tr></thead><tbody><tr><td>Content-type</td><td>application/json</td><td>Specifies the content type of the request</td><td>Yes</td></tr><tr><td>x-metro-api-key</td><td>*************************</td><td>Your API key for authentication purposes.</td><td>Yes</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="199">Field</th><th width="131">Data Type</th><th width="290">Description</th><th>Mandatory</th></tr></thead><tbody><tr><td>caller_number</td><td>String</td><td>Phone number of the caller registered as an agent.</td><td>Yes</td></tr><tr><td>receiver_number</td><td>String</td><td>Phone number of the call recipient.</td><td>Yes</td></tr><tr><td>did_number</td><td>String</td><td>Direct inward dialing number to use, prefixed with country code "91".</td><td>Yes</td></tr><tr><td>is_agent_required</td><td>Boolean</td><td>Specifies whether the <code>caller_number</code> must be registered as an agent on Alohaa. If <code>true</code>, the caller must be an agent; if <code>false</code>, the caller does not need to be registered as an agent.</td><td>No</td></tr><tr><td>webhook_details</td><td>Object</td><td>Webhook configuration to receive details for the <strong>Click-to-Call API trigger</strong>. If a webhook is configured, <code>url</code> and <code>request_type</code> ( are <strong>mandatory</strong>, while <code>api_key</code> and <code>api_value</code> are <strong>optional</strong>. </td><td>No</td></tr><tr><td>did_shuffle</td><td>Boolean</td><td>Default value is <code>false</code> . When set to <code>true</code>, leave the <code>did_number</code>  field empty. The system will automatically randomize calls using numbers from your existing DID pool.</td><td>No</td></tr><tr><td>metadata</td><td>Object</td><td>Key-value pair object to pass custom information along with the call request. These values are stored and returned in webhook payloads. Example: <code>"metadata": {"customerId": "12345", "ticketId": "67890"}</code></td><td>No</td></tr></tbody></table>

{% hint style="info" %}
Good to know:&#x20;

* Before placing a call, caller\_number should be onboarded as an agent in the aloha dashboard, which is a one-time process, if `is_agent_required` is true.
* The prefix "91" is mandatory for did\_number and should not be included for caller\_number and receiver\_number.
* If a webhook is specified in the API request body, it will override and discard any previously configured [outgoing call webhook](/alohaa-docs/webhooks/outgoing-call-webhook.md).
  {% endhint %}

##

<figure><img src="/files/kYbYzRrRjC7DBVkPBFo3" alt=""><figcaption></figcaption></figure>

## Sample Request

{% tabs %}
{% tab title="cURL" %}

```
curl --location 'https://outgoing-call.alohaa.ai/v1/external/click-2-call' \
--header 'x-metro-api-key: <CLIENT_UNIQUE_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "caller_number": "XXXXXX5715",
    "receiver_number": "XXXXXX7182",
    "did_number": "XXXXXXXX8150",
    "did_shuffle": false,
    "is_agent_required": true,
    "metadata": {
        "MetadataName1": "MetadataValue1",
        "MetadataName2": "MetadataValue2"
    },
    "webhook_details": {
        "url": "https://webhook.site/XXXXXXXXXXXX",
        "api_key": "XXXXXXXXXXX",
        "api_value": "XXXXXXXXXXXXXXX",
        "request_type": "POST"
    }
}'
```

{% endtab %}
{% endtabs %}

## Responses

#### Success Response

```
{
  "success": true,
  "response": {
    "reference_id": "642532c24fdbab96d0abe061"
  }
}
```

#### Failure Response

```
{
  "success": false,
  "error": {
    "code": 1043,
    "reason": "Outgoing calls are not allowed for this organisation"
  }
}
```

## Rate Limit

To ensure fair usage and maintain system performance, the Click-to-Call API enforces the following rate limit.

| Limit Type       | Value                 | Description                                                     |
| ---------------- | --------------------- | --------------------------------------------------------------- |
| Per Organization | 1 requests per second | Maximum number of requests allowed per second per organization. |

When rate limits are exceeded, you'll get the following error code:

```
 {
  success: false,
  error: {
    code: 1046,
    reason: 'Rate limit exceeded. Please try again later.'
  }
}
```

{% hint style="warning" %}
**Good to know:**

* Implement exponential backoff or retry mechanisms in your backend.
* For high-volume use cases, contact <support@alohaa.ai> to discuss rate limit adjustments.
  {% endhint %}

## Error Codes

| Code |                                                      |
| ---- | ---------------------------------------------------- |
| 1041 | CRM is not integrated                                |
| 1042 | Organisation is not linked with CRM                  |
| 1043 | Outgoing calls are not allowed for this organisation |
| 1046 | Rate limit exceeded                                  |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.alohaa.ai/alohaa-docs/api/click-to-call-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.