Click to Call API

This API is designed o integrate the "Click to Call" feature into their applications, where users can make an outgoing call without visiting Alohaa portal.

Endpoint Description

POST https://outgoing-call.alohaa.ai/v1/external/click-2-call

Parameters

Request Headers

Field	Value	Description	Mandatory
Content-type	application/json	Specifies the content type of the request	Yes
x-metro-api-key	*************************	Your API key for authentication purposes.	Yes

Request Body

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

Good to know:

• 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.

Sample Request

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

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

Good to know:

• Implement exponential backoff or retry mechanisms in your backend.

• For high-volume use cases, contact [email protected] to discuss rate limit adjustments.

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