Trigger Call API

Programmatically initiate or end a call between a team member and a customer using the Click-to-Call API.

Endpoint

GET https://prod-api.superfone.co.in/superfone/api/customer/click-2-call

Authentication

All requests must include your API key in the X-API-Key header.

X-API-Key: your_api_key_here

info

Don't have an API key? Contact your Superfone account manager or reach out to support to get one provisioned.

Query Parameters

Parameter	Type	Required	Default	Description
customer_number	string	Yes	-	Phone number of the customer to call (E.164 format, e.g., +918000000001)
user_number	string	Yes	-	Phone number of the team member who will make the call (E.164 format)
call_action	string	No	START	Action to perform: START to initiate a call, END to terminate an active call

---

Start a Call

To initiate a call, use call_action=START (or omit it, as START is the default).

Code Examples

cURL

curl -X GET "https://prod-api.superfone.co.in/superfone/api/customer/click-2-call?customer_number=%2B918000000001&user_number=%2B919876543210&call_action=START" \
  -H "X-API-Key: your_api_key_here"

JavaScript

const apiKey = 'your_api_key_here';
const customerNumber = '+918000000001';
const userNumber = '+919876543210';

const url = new URL('https://prod-api.superfone.co.in/superfone/api/customer/click-2-call');
url.searchParams.append('customer_number', customerNumber);
url.searchParams.append('user_number', userNumber);
url.searchParams.append('call_action', 'START');

fetch(url, {
  method: 'GET',
  headers: {
    'X-API-Key': apiKey
  }
})
  .then(response => response.json())
  .then(data => {
    console.log('Call triggered successfully:', data);
  })
  .catch(error => {
    console.error('Error triggering call:', error);
  });

TypeScript

interface ClickToCallResponse {
  data: {
    notificationID: number;
    sentSuccess: boolean;
  };
  message: string;
}

interface ClickToCallParams {
  customer_number: string;
  user_number: string;
  call_action?: 'START' | 'END';
}

async function triggerCall(params: ClickToCallParams): Promise<ClickToCallResponse> {
  const apiKey = 'your_api_key_here';
  
  const url = new URL('https://prod-api.superfone.co.in/superfone/api/customer/click-2-call');
  url.searchParams.append('customer_number', params.customer_number);
  url.searchParams.append('user_number', params.user_number);
  url.searchParams.append('call_action', params.call_action || 'START');

  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'X-API-Key': apiKey
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

// Start a call
triggerCall({
  customer_number: '+918000000001',
  user_number: '+919876543210',
  call_action: 'START'
})
  .then(data => console.log('Call started:', data))
  .catch(error => console.error('Error:', error));

Python

import requests

api_key = 'your_api_key_here'
base_url = 'https://prod-api.superfone.co.in/superfone'

def trigger_call(customer_number, user_number, call_action='START'):
    """
    Trigger a click-to-call action.
    
    Args:
        customer_number (str): Customer's phone number in E.164 format
        user_number (str): Team member's phone number in E.164 format
        call_action (str): 'START' to initiate, 'END' to terminate
    
    Returns:
        dict: Response containing notification details
    """
    url = f'{base_url}/api/customer/click-2-call'
    
    headers = {
        'X-API-Key': api_key
    }
    
    params = {
        'customer_number': customer_number,
        'user_number': user_number,
        'call_action': call_action
    }
    
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    
    return response.json()

# Start a call
result = trigger_call(
    customer_number='+918000000001',
    user_number='+919876543210',
    call_action='START'
)
print('Call started:', result)

What Happens

1. Notification Sent — A notification is sent to the team member's Superfone app
2. Call Initiated — The app automatically initiates a call to the customer
3. Caller ID — The call appears to the customer from your organization's Superfone number
4. Call Logged — The call is logged in your Superfone dashboard

tip

The success response indicates that the notification was sent to the team member's device, not that the call was completed. The actual call connection depends on the team member's device connectivity and the customer answering.

Response

Status Code: 200 OK

{
  "data": {
    "notificationID": 12345,
    "sentSuccess": true
  },
  "message": "success"
}

Field	Type	Description
data.notificationID	number	Identifier for the notification (for tracking purposes)
data.sentSuccess	boolean	Whether the notification was successfully sent to the team member's device
message	string	Status message indicating the result

Error Responses:

Status Code	Message	When It Occurs
400	Invalid request	Missing required parameters or invalid phone number format
401	Unauthorized	Missing or invalid API key
404	User not found	Team member with the specified phone number not found
500	Internal server error	Unexpected server error

---

End a Call

To programmatically terminate an active call, use call_action=END.

Code Examples

cURL

curl -X GET "https://prod-api.superfone.co.in/superfone/api/customer/click-2-call?customer_number=%2B918000000001&user_number=%2B919876543210&call_action=END" \
  -H "X-API-Key: your_api_key_here"

JavaScript

const apiKey = 'your_api_key_here';
const customerNumber = '+918000000001';
const userNumber = '+919876543210';

const url = new URL('https://prod-api.superfone.co.in/superfone/api/customer/click-2-call');
url.searchParams.append('customer_number', customerNumber);
url.searchParams.append('user_number', userNumber);
url.searchParams.append('call_action', 'END');

fetch(url, {
  method: 'GET',
  headers: {
    'X-API-Key': apiKey
  }
})
  .then(response => response.json())
  .then(data => {
    console.log('Call ended successfully:', data);
  })
  .catch(error => {
    console.error('Error ending call:', error);
  });

TypeScript

// Using the same triggerCall function from above

// End an active call
triggerCall({
  customer_number: '+918000000001',
  user_number: '+919876543210',
  call_action: 'END'
})
  .then(data => console.log('Call ended:', data))
  .catch(error => console.error('Error:', error));

Python

# Using the same trigger_call function from above

# End an active call
result = trigger_call(
    customer_number='+918000000001',
    user_number='+919876543210',
    call_action='END'
)
print('Call ended:', result)

What Happens

1. Notification Sent — A notification is sent to the team member's Superfone app
2. Call Terminated — The app ends the ongoing call with the specified customer
3. Call Logged — The call end event is logged in your Superfone dashboard

When to Use

Use the END action when you need to programmatically disconnect a call — for example, when a support ticket is resolved, a time limit is reached, or the customer hangs up on your web interface.

Response

Status Code: 200 OK

{
  "data": {
    "notificationID": 12345,
    "sentSuccess": true
  },
  "message": "success"
}

Field	Type	Description
data.notificationID	number	Identifier for the notification (for tracking purposes)
data.sentSuccess	boolean	Whether the notification was successfully sent to the team member's device
message	string	Status message indicating the result

Error Responses:

Status Code	Message	When It Occurs
400	Invalid request	Missing required parameters or invalid phone number format
401	Unauthorized	Missing or invalid API key
404	User not found	Team member with the specified phone number not found
500	Internal server error	Unexpected server error

---

Notes

Important Considerations

• Phone Number Format: All phone numbers must be in E.164 format (e.g., +918000000001). Numbers without the + prefix or country code will be rejected.
• Dashboard Calling Required: The agent must have Dashboard Calling enabled in their Superfone app. See How to Enable Dashboard Calling for setup instructions.
• App Requirement: The team member must have the Superfone app installed, be logged in, and have the app running in the background with notifications enabled.
• One Active Call Per Agent: Each agent can only have one active call at a time. Triggering a new call for an agent already on a call will fail.
• Network Connectivity: The team member's device must have an active internet connection.

Best Practices

• Error Handling — Always implement proper error handling to manage failed API calls
• Check Agent Availability — Verify the agent is not already on a call before triggering a new one
• Rate Limiting — Be mindful of API rate limits when triggering multiple calls
• Customer Consent — Ensure you have proper consent before initiating calls to customers