Campaigns API

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.
  1. Type parameter value is always 1 for peer to peer dial.
  2. reference_id parameter gives the ability to generate your own unique id, which will be sent along with the webhook response.
  3. user_id is a required parameter which is the user/agent to be dialed
  4. 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.
  1. Type parameter value is always 1 for peer to peer dial.
  2. number should contain a valid phone number with country code, e.g. +919212992129.
  3. 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:
  1. Connect number to any free user in the department mapped to the IVR.
  2. Connect number to automated IVR and collect input.
  3. 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:
  1. 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.
  2. 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.
  3. 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

    • What is the Whatsapp Business API?

      Facebook launched WhatsApp Business API in August 2018 with a vision for the organizations to scale their business and reach out to users in a much better manner on WhatsApp itself. WhatsApp Business API allows businesses to perform the following ...

    • 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 much time does it take to get WhatsApp Business API approved?

      Getting Access to the API is a process via an application that Facebook reviews. You can now directly access WhatsApp Business API from Facebook via WhatsApp Cloud API. But, you'd ultimately still need a platform likeMyOperator to use WhatsApp ...

    • Can I use my Whatsapp Business API account on the Phone?

      Yes, the dashboard provided by MyOperator is compatible with both laptops and mobile. So you can use your WhatsApp Business API account on the phone as well.

    • How to make the transition from WhatsApp App to WhatsApp Business API and vice versa?

      Any phone number can be upgraded to WhatsApp Business API provided the number isn’t active on any of the WhatsApp Apps. So, if a number is registered on WhatsApp App and one needs to get the API on the same number, the WhatsApp Account must be ...