Campaigns API
Overview
MyOperator campaigns can be used to make various types of outgoing calls enabling the client to connect with their customers in ways that suites their business requirement.
Type of Campaigns
According to the use cases, there are 2 types of campaigns that can be used to connect 2 users or connect customers with IVR or department:
Peer to Peer
Peer to peers are the type of calls which can be used to connect 2 parties (mostly customer and agent), MyOperator receives the API request to connect the customer number with the agent passed in the request. MyOperator will initiate the call to both parties one by one and connects them.
IVR based
IVR-based outgoing calls are designed for bulk dialing cases where the customer is connected to any agent who is free in the department. MyOperator receives API requests with a customer number and IVR ID of the outgoing IVR, MyOperator checks if any agent is free in the department provided in the IVR, calls will be queued until someone in the department is free to accept the call.
Authentication Setup
Before using this API, you need to create an account on myoperator.co, after setting up the account you need to apply for campaigns feature, your account manager should guide you through the setup process. After enabling features required in your use case, you will be able to access campaings section on the MyOperator panel located at app.myoperator.co/outbound/campaigns. Follow the documentation for campaings section to get used to the user interface (#todo documentation link).
Setup Parameters
Parameters required in every API request for Authentication
Parameter | Required | Description |
x-api-key | True | Key for accessing API resource |
Secret Token | True | Secret for
accessing API, unique for each account |
Public IVR ID | True | ID referencing a unique campaign, multiple IVRs can be used in an account |
Company ID | True | Unique ID of
an account |
Region | False | When using
Dedicated DID, choose a region for call |
Group | False | When using
Dedicated DID, choose group of a region |
Caller_id | False. | When using
Dedicated DID, choose a dedicated number to make call |
Peer to Peer API
Peer-to-peer API can accept parameters in 2 ways, user dial and anonymous dial. In user dial, the user_id parameter is passed along with a number. In Anonymous dial, two numbers in parameters ( number and number_2 ) are directly passed with any user_id in the request. Anonymous dial only works when the Anonymous feature is enabled for the account. To enable the anonymous feature please contact your account manager.
User Dial HTTP Request
User Dial API request parameters
Shell
curl --request POST 'https://obd-api.myoperator.co/obd-api-v1' \ --header 'x-api-key: {{x-api-key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "company_id": "{{Company ID}}", "secret_token": "{{Secret Token}}", "type": "1", #1 for peer to peer "user_id": "{{User ID}}", "number": "<country_code><number>", #e.g. +919212992129 "public_ivr_id": "{{Public IVR ID}}", "reference_id": "<client request id>", #e.g. abd9238dh21ss "region": <region of a call>, "caller_id": <caller id number of a call>, "group": <group of a dedicated number> }' |
Python
import requests import json url = "https://obd-api.myoperator.co/obd-api-v1" payload = { "company_id": "{{Company ID}}", "secret_token": "{{Secret Token}}", "type": "1", #1 for peer to peer "user_id": "{{User ID}}", "number": "<country_code><number>", #e.g. +919212992129 "public_ivr_id": "{{Public IVR ID}}", "reference_id": "<client request id>", #e.g. abd9238dh21ss "region": "<region of a call>", "caller_id": "<caller id number of a call>", "group": "<group of a dedicated number>" } payload = json.dumps(payload) headers = { 'x-api-key': '{{x-api-key}}', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data = payload) print(response.text.encode('utf8')) |
PHP
<?php $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://obd-api.myoperator.co/obd-api-v1", CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS =>'{ "company_id": "{{Company ID}}", "secret_token": "{{Secret Token}}", "type": "1", //1 for peer to peer "user_id": "{{User ID}}", "number": "<country_code><number>", //e.g. +919212992129 "public_ivr_id": "{{Public IVR ID}}", "reference_id": "<client request id>", //e.g. abd9238dh21ss "region": "<region of a call>", "caller_id": "<caller id number of a call>", "group": "<group of a dedicated number>" }', CURLOPT_HTTPHEADER => array( "x-api-key: {{x-api-key}}", "Content-Type: application/json" ), )); $response = curl_exec($curl); curl_close($curl); echo $response; |
Nodejs
var request = require('request'); var body = { "company_id": "{{Company ID}}", "secret_token": "{{Secret Token}}", "type": "1", //1 for peer to peer "user_id": "{{User ID}}", "number": "<country_code><number>", //e.g. +919212992129 "public_ivr_id": "{{Public IVR ID}}", "reference_id": "<client request id>", //e.g. abd9238dh21ss "region": "<region of a call>", "caller_id": "<caller id number of a call>", "group": "<group of a dedicated number>" }; var options = { 'method': 'POST', 'url': 'https://obd-api.myoperator.co/obd-api-v1', 'headers': { 'x-api-key': '{{x-api-key}}', 'Content-Type': 'application/json' }, body: JSON.stringify(body) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); |
POST https://obd-api.myoperator.co/obd-api-v1 |
In User dial, by default User is called first, if the user picks up the call then the number will be dialed. To reverse this direction ( i.e. dial customer first), you can change the Dial First setting in the campaign section.
- Type parameter value is always 1 for peer to peer dial.
- reference_id parameter gives the ability to generate your own unique id, which will be sent along with the webhook response.
- user_id is a required parameter which is the user/agent to be dialed
- number should contain a valid phone number with country code, e.g. +919212992129.
Response of the API is provided in the API response section.
Anonymous User Dial HTTP Request
Anonymous Dial API request parameters
Shell
curl --request POST 'https://obd-api.myoperator.co/obd-api-v1' \ --header 'x-api-key: {{x-api-key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "company_id": "{{Company ID}}", "secret_token": "{{Secret Token}}", "type": "1", #1 for peer to peer "number": "<country_code><number>", "number_2": "<country_code><number>", #e.g. +919212992129 "public_ivr_id": "{{Public IVR ID}}", "reference_id": "<client request id>", #e.g. abd9238dh21ss "region": "<region of a call>", "caller_id": "<caller id number of a call>", "group": "<group of a dedicated number>" }' |
Python
import requests import json url = "https://obd-api.myoperator.co/obd-api-v1" payload = { "company_id": "{{Company ID}}", "secret_token": "{{Secret Token}}", "type": "1", #1 for peer to peer "number": "<country_code><number>", #e.g. +919212992129 "number_2": "<country_code><number>", #e.g. +919999999999 "public_ivr_id": "{{Public IVR ID}}", "reference_id": "<client request id>", #e.g. abd9238dh21ss "region": "<region of a call>", "caller_id": "<caller id number of a call>", "group": "<group of a dedicated number>" } payload = json.dumps(payload) headers = { 'x-api-key': '{{x-api-key}}', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data = payload) print(response.text.encode('utf8')) |
PHP
<?php $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://obd-api.myoperator.co/obd-api-v1", CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS =>'{ "company_id": "{{Company ID}}", "secret_token": "{{Secret Token}}", "type": "1", //1 for peer to peer "number": "<country_code><number>", //e.g. +919212992129 "number_2": "<country_code><number>", //e.g. +919999999999 "public_ivr_id": "{{Public IVR ID}}", "reference_id": "<client request id>", //e.g. abd9238dh21ss "region": "<region of a call>", "caller_id": "<caller id number of a call>", "group": "<group of a dedicated number>" }', CURLOPT_HTTPHEADER => array( "x-api-key: {{x-api-key}}", "Content-Type: application/json" ), )); $response = curl_exec($curl); curl_close($curl); echo $response; |
Nodejs
var request = require('request'); var body = { "company_id": "{{Company ID}}", "secret_token": "{{Secret Token}}", "type": "1", //1 for peer to peer "number": "<country_code><number>", //e.g. +919212992129 "number_2": "<country_code><number>", //e.g. +919999999999 "public_ivr_id": "{{Public IVR ID}}", "reference_id": "<client request id>", //e.g. abd9238dh21ss "region": "<region of a call>", "caller_id": "<caller id number of a call>", "group": "<group of a dedicated number>" }; var options = { 'method': 'POST', 'url': 'https://obd-api.myoperator.co/obd-api-v1', 'headers': { 'x-api-key': '{{x-api-key}}', 'Content-Type': 'application/json' }, body: JSON.stringify(body) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); |
POST https://obd-api.myoperator.co/obd-api-v1 |
In Anonymous dial Dial first setting will work from IVR settings in the campaigns section to change the order of dialing ( number first or number_2 first). You can also, switch the values of parameters number and number_2 to achive the same.
- Type parameter value is always 1 for peer to peer dial.
- number should contain a valid phone number with country code, e.g. +919212992129.
- number_2 should contain a valid phone number with country code, e.g. +919212992129.
IVR based API
IVR-based is used to connect a number with an IVR public_ivr_id . IVR can be configured in many ways to satisfy the given requirement, most common causes are:
- Connect number to any free user in the department mapped to the IVR.
- Connect number to automated IVR and collect input.
- Connect number with IVR configured with input node (feature for dynamic IVR execution).
IVR can be configured according to the requirement in the MyOperator campaigns section.
IVR based HTTP Request
IVR Dial API request parameters
Shell
curl --request POST 'https://obd-api.myoperator.co/obd-api-v1' \ --header 'x-api-key: {{x-api-key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "company_id": "{{Company ID}}", "secret_token": "{{Secret Token}}", "type": "2", "number": "<country_code><number>", #e.g. +919212992129 "public_ivr_id": "{{Public IVR ID}}", "reference_id": "<client request id>", #e.g. abd9238dh21ss "region": "<region of a call>", "caller_id": "<caller id number of a call>", "group": "<group of a dedicated number>" }' |
Python
import requests import json url = "https://obd-api.myoperator.co/obd-api-v1" payload = { "company_id": "{{Company ID}}", "secret_token": "{{Secret Token}}", "type": "2", #2 forIVR "number": "<country_code><number>", #e.g. +919212992129 "public_ivr_id": "{{Public IVR ID}}", "reference_id": "<client request id>", #e.g. abd9238dh21ss "region": "<region of a call>", "caller_id": "<caller id number of a call>", "group": "<group of a dedicated number>" } payload = json.dumps(payload) headers = { 'x-api-key': '{{x-api-key}}', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data = payload) print(response.text.encode('utf8')) |
PHP
<?php $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://obd-api.myoperator.co/obd-api-v1", CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS =>'{ "company_id": "{{Company ID}}", "secret_token": "{{Secret Token}}", "type": "2", //2 for IVR "number": "<country_code><number>", //e.g. +919212992129 "public_ivr_id": "{{Public IVR ID}}", "reference_id": "<client request id>", //e.g. abd9238dh21ss "region": "<region of a call>", "caller_id": "<caller id number of a call>", "group": "<group of a dedicated number>" }', CURLOPT_HTTPHEADER => array( "x-api-key: {{x-api-key}}", "Content-Type: application/json" ), )); $response = curl_exec($curl); curl_close($curl); echo $response; |
Nodejs
var request = require('request'); var body = { "company_id": "{{Company ID}}", "secret_token": "{{Secret Token}}", "type": "2", //2 for IVR "number": "<country_code><number>", //e.g. +919212992129 "public_ivr_id": "{{Public IVR ID}}", "reference_id": "<client request id>", //e.g. abd9238dh21ss "region": "<region of a call>", "caller_id": "<caller id number of a call>", "group": "<group of a dedicated number>" }; var options = { 'method': 'POST', 'url': 'https://obd-api.myoperator.co/obd-api-v1', 'headers': { 'x-api-key': '{{x-api-key}}', 'Content-Type': 'application/json' }, body: JSON.stringify(body) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); |
In IVR based calls type parameter is always 2. Settings which worked in peer to peer like dial first will not work since we only have one parameter as number is passed. the number is a required parameter which is should contain the country code. reference_id parameter gives the ability to generate your own unique id, which will be sent along with the webhook response.
Dedicated DID Filters
Campaigns API has 3 parameters which you can use to manage the dedicated DID's. Before dedicated DID's can be sent as a parameter, you have to purchase them from the Dedicated DID section and configure them in campaign IVR. Please check the Campaign documentation for more detail.
Dedicated DID parameters (region, group, caller_id) are called Dedicated DID filters. User can use dedicated DID in calling process in many ways:
Filters not passed in params
If no dedicated DID filters are passed as a parameter, then MyOperator will check for any Dedicated DID assign to the IVR ( which can be managed from the campaign settings section ). If no Dedicated DID is assigned, the call will go from the shared route ( if the shared route is enabled in advanced settings in the campaign section ).
Filters passed in params
If filters are passed, one thing to be noted is, not all 3 filters need to be passed as parameters. MyOperator can automatically choose a random dedicated DID if the filter has many dedicated DID available. For example, if you have purchased 8 DIDs in 2 regions (Delhi and Noida) in 2 groups in each region, 2 DID in each group, like below:
Region | Group | DID |
Delhi | gr1 | 011609821 |
Delhi | gr1 | 011609822 |
Delhi | gr2 | 011709821 |
Delhi | gr2 | 011709822 |
Noida | gr3 | 0122666661 |
Noida | gr3 | 0122666662 |
Noida | gr4 | 0122766661 |
Noida | gr4 | 0122766662 |
Different cases and how the process will work is provided below:
Case | Params | Process |
Only Region | region: "Delhi" | MyOperator will select a random group from avaiable groups (gr1 , gr2) in region and selects a random DID from selected group. So MyOperator can randomly call from any DID in Delhi region |
Only Group | group: "gr1" | MyOperator will select a random DID from gr1 |
Only DID | caller_id: "011609822" | MyOperator will call using DID 011609822 |
All params | region:"Delhi", group:"gr1", caller_id:"011609822" | MyOperator checks the params with priority caller_id, group, region. If higher priority param is found then rest params will be ignored. So, in this case since caller_id is passed, MyOperator will use caller_id parameter directly, other params (group and region) will be ignored. |
Important points:
- Please double-check if caller_id passed is purchased and it is incorrect format, If caller_id parameter is invalid, API will accept the request and will not be able to call using dedicated DID.
- Using multiple groups and regions will ensure the uptime of your service. MyOperator will automatically shift the load to another group ( detecting and removing the group might take a few minutes). It is recommended to pass only region parameters and let MyOperator autoselect group according to availability.
- If you want to use only one DID for calling and want to use other DIDs as failover, then send DID in caller_id parameter, if group if selected DID is down, MyOperator can still use other Dedicated DID of any region if failover Global setting is enabled.
API Response
Whenever a request is received by campaigns API, an acknowledgment is sent in response with the below parameters.
Success response body parameters
{ "details": "Request accepted successfully", "status": "success", "code": "200", "unique_id": "<unique_generated_request_id>", "reference_id": "<optional param will be present if provided in request_body>" } |
Description of parameters of this acknowledgment message are provided below:
|
Parameter |
Description |
|
details |
parameter gives the detailed message of the status of request. |
|
status |
status of request,
could be either success or error
|
|
code |
http status code of the request, different error codes are defined in errors section |
|
unique_id |
this is a unique id generated by MyOperator for a request |
|
reference_id |
if reference id is present in the API request, same will be
returned |
Error codes
When an API request is sent, it could failed due to various reason, code parameter in API response can help in understanding the issue.
Missing or invalid x-api-key
If x-api-key parameter in header is missing, you will get error like below:
{ "message": "Forbidden", "type": "INVALID_API_KEY", "code": "403", "status": "error", "stage": "prod", "resourcePath": "/obd-api-v1", "details": "" } |
Error response message body parameters
For other error messages will have the below format:
{ "details": "{msg}", "status": "error", "code": "<code>", "unique_id": "<unique_generated_request_id>", "reference_id": "<optional param will be present if provided in request_body>" } |
The MyOperator API uses the following error codes:
|
Error Code |
Meaning |
|
400 |
Bad Request -- Your request is invalid. check for missing parameter, request method etc. |
|
403 |
Forbidden -- may cause due to billing issue, too many requests for same number, or invalid IP etc. |
|
404 |
Not Found -- The specified resource could not be found. Check requested URL. |
|
500 |
Internal Error -- We had a problem
with our server.
Try again later
after some time or generate support ticket. |
Some common error messages are:
|
Error Code |
Message |
Description |
|
400 |
Provide valid Number in string format |
|
|
400 |
Provide valid Agent Number in string format |
|
|
400 |
Provide valid type in string format |
type parameter is invalid, please check documentation |
|
400 |
Provide only one a Valid user_id or number_2 in string format |
|
|
400 |
Provide either a Valid user_id or number_2 in string format |
|
|
400 |
Provide valid secret_token in string format |
|
|
403 |
Your IP is unauthorized access denied |
Requester IP is not in Valid IP list, conteact support |
|
403 |
Your annonymous feature is not enabled |
contact support team |
|
403 |
User_id or number_2(agent_number) not allowed for this type |
|
|
403 |
Kindly choose any other reference ID, it has been already taken. Reference ID remaining_ttl x seconds |
duplicate reference ID is not allowed for a certain time, please contact support team to change setting |
|
403 |
Your billing usage has been Expired. |
Billing issue please contact support team |
|
403 |
Maximum number of requests for this number have exceeded. |
Call on same number is allowed only few times in a day, please contact support to change setting. |
|
404 |
Provide valid public_ivr_id in string format |
|
|
500 |
We are unable to process your request due to incomplete company_details |
Configuration Issue, pleae contact support team |
Related Articles
How do I find my API key?
To find your API key, follow the steps mentioned below: 1. Login to Freshdesk. 2. Click on the “Logo” at the top right. 3. Click on “Profile Settings”. 4.Your “API Key” is on the bottom left of the page.How does variable mapping work in WhatsApp campaigns?
Variable mapping connects placeholders (e.g., {{customername}}) in the template to actual data (e.g., the "Name" column in your Excel sheet). It ensures personalized messages are sent. In a template with variables like {{customername}}, {{amount}}, ...How long does a conversation last on WhatsApp Business API?
Each conversation lasts 24 hours from the time a message is delivered, unless it is closed by a newly opened free-entry point conversation, which lasts 72 hours.What is conversation-based pricing on WhatsApp Business API?
Conversation-based pricing charges businesses per conversation, not per individual message sent or received. Each conversation is a 24-hour message thread between the business and the customer.How can I access the Campaign Feature in WhatsApp?
You can access the feature by going to Manage > WhatsApp > Campaigns > Create Campaigns.