NAV
shell ruby python javascript java go php

INTRODUCTION

MyServiceAgent Developer Documentation

Version: 0.1.0

Welcome to the MyServiceAgent API documentation. It guides developers on how to integrate amazing customer engagement interactions into their applications using the MyServiceAgent voice and SMS REST APIs.

Before you get started, make sure you have the following covered

  1. Create a developer account on the https://myserviceagent.net platform.
  2. Retrieve your API key from your myserviceagent.net dashboard
  3. Purchase sufficient airtime units

Now that you have those covered, here are some other basic things you should know.

Authentication

The MyServiceAgent API uses the standard header authorization to authenticate API requests.

Authorization header parameter must be sent with all client requests. The value helps the server to validate and identify the request source. The required value is Bearer <YOUR_API_KEY>

apiKey API Key
Authorization Bearer

Find out more about MyServiceAgent Developer Platform

Content Types

The MyServiceAgent API generally accepts two content types; JSON for requests that do not require a file upload and form data for requests that require a file upload.

The Content-Type header parameter should be sent with all client requests. The possible values are application/json and multipart/form-data.

All set? Check out our available endpoints below and get started with integrating.

Telemarketing APIs

The telemarketing APIs enable you to send SMS or voice messages to one or more phone numbers. You can also view the delivery status of a single SMS or voice message. In this documentation, a phone number is referred to as MSISDN.

Create an SMS Telemarketing Job

With this endpoint, you can instantly send or schedule a message to one or more phone numbers or to a phonebook you’ve created on your myserviceagent.net dashboard. Numbers should always include the dialing code prefix. If you’ve registered a custom sender ID from the myserviceagent.net dashboard, you can specify the value in your request body so that the phone numbers can receive the SMS from your sender ID.

curl --location --request POST 'https://api.myserviceagent.net/api/v1/telemarketing/sms' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name" : "New Telemarketing Job",
    "msisdns" : "+2348000000001,+2348000000000",
    "message_text" : "New Telemarketing Job Message",
    "run_time" : "2020-12-23 17:00:00"
}'



import requests

url = "https://api.myserviceagent.net/api/v1/telemarketing/sms"

payload={
  "name" : "New Telemarketing Job",
  "msisdns" : "+2348000000001,+2348000000000",
  "message_text" : "New Telemarketing Job Message",
  "run_time" : "2020-12-23 17:00:00"
}

headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)


<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/telemarketing/sms');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));
$request->setBody('{
\n    "name" : "New Telemarketing Job",
\n    "msisdns" : "+2348000000001,+2348000000000",
\n    "message_text" : "New Telemarketing Job Message",
\n    "run_time" : "2020-12-23 17:00:00"
\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}



package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/telemarketing/sms"
  method := "POST"

  payload := strings.NewReader(`{`+"
"+`
    "name" : "New Telemarketing Job",`+"
"+`
    "msisdns" : "+2348000000001,+2348000000000",`+"
"+`
    "message_text" : "New Telemarketing Job Message",`+"
"+`
    "run_time" : "2020-12-23 17:00:00"`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  name: "New Telemarketing Job",
  msisdns: "+2348000000001,+2348000000000",
  message_text: "New Telemarketing Job Message",
  run_time: "2020-12-23 17:00:00",
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.myserviceagent.net/api/v1/telemarketing/sms", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "status": true,
  "message": "Job Created",
  "data": {
    "name": "New Telemarketing Job",
    "client_id": 38,
    "msisdns": "+2348000000001,+2348000000000",
    "type": "sms",
    "message_text": "New Telemarketing Job Message",
    "run_time": "2020-12-23 20:00:00",
    "updated_at": "2020-12-23 19:08:14",
    "created_at": "2020-12-23 19:08:14",
    "id": 60
  }
}

HTTP Request

POST https://api.myserviceagent.net/api/v1/telemarketing/sms

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Body Parameters

Name Located in Description Required Type
authorization header Enter your generated API key Yes string
name json body Name of Telemarketing Job/Message Yes string
msisdns json body MSISDNs Yes string
message_text json body Message Text Yes string
run_time json body Optionally supply a run time. i.e 2020-12-25 12:40:12 or any other valid Datetime string. The job will be processed instantly if this parameter is not supplied. No string
sender_id json body Optionally specify a sender id to be used to deliver the message. The sender id must have been registered and approved on your MyserviceAgent dashboard. When not sent, a generic sender id will be used to deliver the message. NOTE: This only works for local(Nigerian) numbers. No strong

Responses

Code Description
200 Successful - Response data
400 Bad Request
401 Unauthorized API key
405 Invalid input

Create a Voice Telemarketing Job

With this endpoint, you can instantly send or schedule a voice message to one or more phone numbers or to a phonebook you’ve created on your myserviceagent.net dashboard.

If you have obtained one or more phone numbers, you can send any of them as the phone_number parameter so that the recipient receives the call with the specified phone number.

Voice messages may be uploaded in wav or mp3 formats. You may also send a text message that will be converted to audio by our system.

Numbers should include the country code prefix.

curl --location --request POST 'https://api.myserviceagent.net/api/v1/telemarketing/voice' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--form 'name="New Voice Telemarketing Job"' \
--form 'msisdns="+2348000000001,+2348000000000"' \
--form 'message_audio=@"/C:/Users/IT/Downloads/NewVoiceTelemarketingAudio.mp3"' \
--form 'run_time="2020-12-24 13:00:12"'



import requests

url = "https://api.myserviceagent.net/api/v1/telemarketing/voice"

payload={
  'name': 'New Voice Telemarketing Job',
  'msisdns': '+2348000000001,+2348000000000',
  'run_time': '2020-12-24 13:00:12'
}

files=[
  ('message_audio',('NewVoiceTelemarketingAudio.mp3',open('/C:/Users/IT/Downloads/NewVoiceTelemarketingAudio.mp3','rb'),'audio/mpeg'))
]
headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>'
}

response = requests.request("POST", url, headers=headers, json=payload, files=files)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");

var formdata = new FormData();
formdata.append("name", "New Voice Telemarketing Job");
formdata.append("msisdns", "+2348000000001,+2348000000000");
formdata.append(
  "message_audio",
  fileInput.files[0],
  "/C:/Users/IT/Downloads/NewVoiceTelemarketingAudio.mp3"
);
formdata.append("run_time", "2020-12-24 13:00:12");

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: formdata,
  redirect: "follow",
};

fetch(
  "https://api.myserviceagent.net/api/v1/telemarketing/voice",
  requestOptions
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));



<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/telemarketing/voice');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>'
));
$request->addPostParameter(array(
  'name' => 'New Voice Telemarketing Job',
  'msisdns' => '+2348000000001,+2348000000000',
  'run_time' => '2020-12-24 13:00:12'
));
$request->addUpload('message_audio', '/C:/Users/IT/Downloads/NewVoiceTelemarketingAudio.mp3', '/C:/Users/IT/Downloads/NewVoiceTelemarketingAudio.mp3', '<Content-Type Header>');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "bytes"
  "mime/multipart"
  "os"
  "path/filepath"
  "io"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/telemarketing/voice"
  method := "POST"

  payload := &bytes.Buffer{}
  writer := multipart.NewWriter(payload)
  _ = writer.WriteField("name", "New Voice Telemarketing Job")
  _ = writer.WriteField("msisdns", "+2348000000001,+2348000000000")
  file, errFile3 := os.Open("/C:/Users/IT/Downloads/NewVoiceTelemarketingAudio.mp3")
  defer file.Close()
  part3,
         errFile3 := writer.CreateFormFile("message_audio",filepath.Base("/C:/Users/IT/Downloads/NewVoiceTelemarketingAudio.mp3"))
  _, errFile3 = io.Copy(part3, file)
  if errFile3 != nil {
    fmt.Println(errFile3)
    return
  }
  _ = writer.WriteField("run_time", "2020-12-24 13:00:12")
  err := writer.Close()
  if err != nil {
    fmt.Println(err)
    return
  }


  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")

  req.Header.Set("Content-Type", writer.FormDataContentType())
  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{
  "status": true,
  "message": "Job Created",
  "data": {
    "name": "New Voice Telemarketing Job",
    "client_id": 38,
    "msisdns": "+2348000000001,+2348000000000",
    "run_time": "2020-12-24 13:00:12",
    "message_audio": "https://crm-api.myserviceagent.net/uploads/telejobs/audio/--1608737382.mp3",
    "updated_at": "2020-12-23 16:29:42",
    "created_at": "2020-12-23 16:29:42",
    "id": 58
  }
}

HTTP Request

POST https://api.myserviceagent.net/api/v1/telemarketing/voice

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Body Parameters

Name Located in Description Required Type
name formData Name of Telemarketing Job/Message Yes string
msisdns formData A list of phone numbers separated by comma that the call will be sent to. Each phone number should be in this format: 2348000000000 No string
message_audio formData Audio file containing the message. No file
message_text formData Message text to convert to audio No string
webhook_url formData Your webhook url No string
phonebook_id formData id of a phonebook associated with the user account. Can be sent in place of the msisdns field.
run_time formData Run time i.e 2020-12-25 12:40:12. Do not send this parameter if you want the job to be processed immediately. No string
external_id formData associate an identifier from your database with this job. Must be a string not greater than 144 characters.12:40:12 No
expiry_time formData Optionally supply an expiry time. i.e 2023-12-25 12:40:12. Calls will stop being processed once the specified time has elapsed. No string
phone_number formData A phone number associated with the user account. When specified, the recipient(s) will receive the call with this number. No string

Responses

Code Description
200 Successful - Response data
400 Bad Request
401 Unauthorized API key
405 Invalid input

Send a WhatsApp Telemarketing job

With this endpoint, you can instantly send a WhatsApp message to one or more phone numbers or to a phonebook you’ve created on your myserviceagent.net dashboard. Numbers should always include the dialing code prefix. An approved WhatsApp template is required to call this endpoint. If you’ve registered a WhatsApp template from the myserviceagent.net dashboard that has been approved, you can specify the template ID as the template parameter in your request body.

NB: Please push not more than 1k numbers per request.

curl --location -g --request POST 'https://api.myserviceagent.net/api/v1/telemarketing/whatsapp' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{

"name": "test mic 12345",
"template": "hello universe",
"msisdns": "+2348222333555"
}'

<?php
$api_url = ' https://api.myserviceagent.net/api/v1/telemarketing/whatsapp' ;
$api_key = '<YOUR_API_KEY>';

$data = array(
    "name" => "New Telemarketing Job",
    "msisdns" => "+2348000000001,+2348000000000",
    "template" => "marketing_331"
);

$headers = array(
    'Authorization: Bearer ' . $api_key,
    'Content-Type: application/json'
);

$ch = curl_init($api_url);

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);

$http_status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($http_status == 200) {
    echo $response;
} else {
    echo 'Unexpected HTTP status: ' . $http_status;
}

curl_close($ch);
?>

The above command returns JSON structured like this:

{
  "status": true,
  "message": "WhatsApp broadcast sent",
  "data": {
    "name": "test mic 12345",
    "client_id": 12,
    "type": "whatsapp",
    "whatsapp_template": "hello universe",
    "sender_id": null,
    "run_time": "2022-11-17T23:15:13.474757Z",
    "updated_at": "2022-11-18 00:15:13",
    "created_at": "2022-11-18 00:15:13",
    "id": 133,
    "reciepentsno": 1,
    "cost": "calculated"
  }
}

HTTP Request

POST https://api.myserviceagent.net/api/v1/telemarketing/whatsapp

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Body Parameters

Name Located in Description Required Type
name json body identifies the telemarketing job Yes string
msisdns json body A list of phone numbers separated by comma. should be in the format 2348000000000 No string
phonebook_id json body id of a phonebook associated with the user. Can be sent in place of the msisdns field. No string
template json body An approved WhatsApp template is required Yes string

Responses

Code Description
200 Successful - Response data
400 Bad Request
401 Unauthorized API key
405 Invalid input

Get all Telemarketing Jobs

With this endpoint, you can get all your telemarketing jobs. The data returned is paginated. Using the id values returned with the jobs, you can get more details of the items associated with any of the jobs when you call the Get all queues for a telemarketing job endpoint.

curl --location --request GET 'https://api.myserviceagent.net/api/v1/telemarketing/customer' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "page" : 1
}'



import requests

url = "https://api.myserviceagent.net/api/v1/telemarketing/customer"

payload= {
  "page" : 1
}
headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({ page: 1 });

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch(
  "https://api.myserviceagent.net/api/v1/telemarketing/customer",
  requestOptions
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/telemarketing/customer');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));
$request->setBody('{
\n    "page" : 1
\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}



package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/telemarketing/customer"
  method := "GET"

  payload := strings.NewReader(`{`+"
"+`
    "page" : 1`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{
  "status": true,
  "message": "Success",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 13,
        "name": "Merry christmas",
        "client_id": 38,
        "message_audio": null,
        "status": "success",
        "message_text": "Merry Christmas and Happy new year in advance",
        "msisdns": "07085140175",
        "run_time": "2020-12-20 21:56:00",
        "deleted_at": null,
        "created_at": "2020-12-18 15:24:53",
        "updated_at": "2020-12-18 15:24:53",
        "type": "sms",
        "message_ids": "msg_5fe033be5823d"
      },
      {
        "id": 14,
        "name": "This is the movement",
        "client_id": 38,
        "message_audio": null,
        "status": "success",
        "message_text": "This is the movement",
        "msisdns": "+2348000000001",
        "run_time": "2020-12-18 17:43:51",
        "deleted_at": null,
        "created_at": "2020-12-18 17:43:51",
        "updated_at": "2020-12-18 17:43:52",
        "type": "sms",
        "message_ids": "msg_5fdcdc474daa9"
      },
      {
        "id": 15,
        "name": "This is the movement",
        "client_id": 38,
        "message_audio": null,
        "status": "new",
        "message_text": "This is the movement",
        "msisdns": "+2348000000001",
        "run_time": "2020-12-26 16:30:26",
        "deleted_at": null,
        "created_at": "2020-12-18 18:00:32",
        "updated_at": "2020-12-18 18:00:32",
        "type": "sms",
        "message_ids": null
      },
      {
        "id": 16,
        "name": "This is the movement",
        "client_id": 38,
        "message_audio": "https://crm-api.myserviceagent.net/uploads/telejobs/audio/38--1608311515.mp3",
        "status": "new",
        "message_text": null,
        "msisdns": "+2348000000001",
        "run_time": "2020-12-18 18:11:55",
        "deleted_at": null,
        "created_at": "2020-12-18 18:11:55",
        "updated_at": "2020-12-18 18:11:55",
        "type": "voice",
        "message_ids": null
      },
      {
        "id": 17,
        "name": "Testing the Voice call",
        "client_id": 38,
        "message_audio": "https://crm-api.myserviceagent.net/uploads/telejobs/audio/38--1608312031.mp3",
        "status": "new",
        "message_text": null,
        "msisdns": "+2348000000001",
        "run_time": "2020-12-21 00:00:21",
        "deleted_at": null,
        "created_at": "2020-12-18 18:20:31",
        "updated_at": "2020-12-18 18:20:31",
        "type": "voice",
        "message_ids": null
      },
      {
        "id": 18,
        "name": "Testing the Time schedule",
        "client_id": 38,
        "message_audio": null,
        "status": "success",
        "message_text": "Testing the Time schedule",
        "msisdns": "+2348000000001",
        "run_time": "2020-12-18 18:21:44",
        "deleted_at": null,
        "created_at": "2020-12-18 18:21:44",
        "updated_at": "2020-12-18 18:21:45",
        "type": "sms",
        "message_ids": "msg_5fdce5291fa4c"
      },
      {
        "id": 19,
        "name": "Testing the SMS text",
        "client_id": 38,
        "message_audio": null,
        "status": "success",
        "message_text": "Believe in yourself bro.",
        "msisdns": "+2348000000001",
        "run_time": "2020-12-20 00:31:58",
        "deleted_at": null,
        "created_at": "2020-12-20 00:31:58",
        "updated_at": "2020-12-20 00:31:59",
        "type": "sms",
        "message_ids": "msg_5fde8d6e9a9ec"
      },
      {
        "id": 20,
        "name": "Testing the SMS feature again",
        "client_id": 38,
        "message_audio": null,
        "status": "success",
        "message_text": "I love you all",
        "msisdns": "+2348000000001",
        "run_time": "2020-12-20 00:58:46",
        "deleted_at": null,
        "created_at": "2020-12-20 00:58:46",
        "updated_at": "2020-12-20 00:58:47",
        "type": "sms",
        "message_ids": "msg_5fde93b71cd5f"
      },
      {
        "id": 21,
        "name": "New Test",
        "client_id": 38,
        "message_audio": null,
        "status": "new",
        "message_text": "Just testing again",
        "msisdns": "+2348000000001",
        "run_time": "2020-12-24 01:30:24",
        "deleted_at": null,
        "created_at": "2020-12-20 01:19:05",
        "updated_at": "2020-12-20 01:19:05",
        "type": "sms",
        "message_ids": null
      },
      {
        "id": 22,
        "name": "Another Test",
        "client_id": 38,
        "message_audio": null,
        "status": "success",
        "message_text": "Another test",
        "msisdns": "+2348000000001",
        "run_time": "2020-12-20 01:21:22",
        "deleted_at": null,
        "created_at": "2020-12-20 01:21:22",
        "updated_at": "2020-12-20 01:21:23",
        "type": "sms",
        "message_ids": "msg_5fde9902ac20f"
      }
    ],
    "first_page_url": "https://crm-api.myserviceagent.net/api/v1/telemarketing/customer?page=1",
    "from": 1,
    "last_page": 2,
    "last_page_url": "https://crm-api.myserviceagent.net/api/v1/telemarketing/customer?page=2",
    "next_page_url": "https://crm-api.myserviceagent.net/api/v1/telemarketing/customer?page=2",
    "path": "https://crm-api.myserviceagent.net/api/v1/telemarketing/customer",
    "per_page": 10,
    "prev_page_url": null,
    "to": 10,
    "total": 16
  },
  "client": {
    "id": 38,
    "client_name": "",
    "contact_person": "similoluwa okunowo",
    "organization_type": "Developer",
    "email": "rexsimiloluwa@gmail.com",
    "phone_number": "7085140175",
    "status": "offline",
    "sub_status": "inactive",
    "website": null,
    "airtime_balance": 1969,
    "sms_balance": 0,
    "inbound_calls": 0,
    "outbound_calls": 0,
    "dropped_calls": 0,
    "deleted_at": null,
    "last_call": "2020-12-21 00:05:32",
    "created_at": "2020-11-23 15:32:29",
    "updated_at": "2020-12-22 09:58:10",
    "type": "profit",
    "supports_international": "yes",
    "software_developer": "yes",
    "dev_platform": "yes",
    "phone_verified": 0,
    "email_verified": 1,
    "country": "nigeria",
    "otp_code": null,
    "wallet_notification": "yes",
    "autorenew": "no",
    "accepted_terms": "yes"
  }
}

HTTP Request

GET https://api.myserviceagent.net/api/v1/telemarketing/customer

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Query Parameters

Name Located in Description Required Type
page formData Page number No long

Responses

Code Description
200 Response data
400 Please enter your API Key
401 Unauthorized or Invalid API key
404 No Telemarketing Jobs

Get all Queues for a Job

When you’ve dispatched or scheduled a telemarketing job, you can call this endpoint to return all the items associated with the job. The id of the telemarketing job is required to call this endpoint. The id is returned when the telemarketing job is created or when you call the Get all telemarketing jobs endpoint. The paginated data returned when this endpoint is called will include the status of the individual items and in some cases, the delivery status.

curl --location --request GET 'https://api.myserviceagent.net/api/v1/telemarketing/queues/1' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "page" : 1
}'

require "uri"
require "net/http"

url = URI("https://api.myserviceagent.net/api/v1/telemarketing/queues/1")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"
request.body = {
  "page" : 1
}

response = https.request(request)
puts response.read_body

import requests

url = "https://api.myserviceagent.net/api/v1/telemarketing/queues/1"

payload= {
  "page" : 1
}
headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({ page: 1 });

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch(
  "https://api.myserviceagent.net/api/v1/telemarketing/queues/1",
  requestOptions
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/telemarketing/queues/1');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));
$request->setBody('{
\n    "page" : 1
\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/telemarketing/queues/1"
  method := "GET"

  payload := strings.NewReader(`{   `+"
"+`
    "page" : 1`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{
  "status": true,
  "message": "Success",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 1,
        "name": "test job",
        "client_id": 1,
        "job_id": 1,
        "message_audio": "https://crm-api.myserviceagent.net/uploads/telejobs/audio/1--1604158018.wav",
        "message_text": null,
        "msisdn": "08124163122",
        "status": "processed",
        "run_time": "2020-10-31 17:47:49",
        "created_at": "2020-10-31 16:26:58",
        "updated_at": "2020-10-31 16:26:58",
        "client": {
          "id": 1,
          "client_name": "NCDC Test",
          "contact_person": "MSA Team",
          "organization_type": "Government",
          "email": "msa@iqubelabs.com",
          "phone_number": "08124163122",
          "status": "online",
          "sub_status": "active",
          "website": "https://myserviceagent.net",
          "airtime_balance": 40,
          "sms_balance": 93,
          "inbound_calls": 15,
          "outbound_calls": 14,
          "dropped_calls": 10,
          "deleted_at": null,
          "last_call": "2020-11-02 00:20:18",
          "created_at": "2020-06-11 20:23:22",
          "updated_at": "2020-07-03 19:12:58",
          "type": "profit",
          "supports_international": "yes",
          "software_developer": "no",
          "dev_platform": "no",
          "phone_verified": 0,
          "email_verified": 0,
          "country": "Nigeria",
          "otp_code": null,
          "wallet_notification": "yes",
          "autorenew": "no",
          "accepted_terms": "no"
        }
      },
      {
        "id": 2,
        "name": "test job",
        "client_id": 1,
        "job_id": 1,
        "message_audio": "https://crm-api.myserviceagent.net/uploads/telejobs/audio/1--1604158018.wav",
        "message_text": null,
        "msisdn": "08133150074",
        "status": "processed",
        "run_time": "2020-10-31 17:47:49",
        "created_at": "2020-10-31 16:26:58",
        "updated_at": "2020-10-31 16:26:58",
        "client": {
          "id": 1,
          "client_name": "NCDC Test",
          "contact_person": "MSA Team",
          "organization_type": "Government",
          "email": "msa@iqubelabs.com",
          "phone_number": "08124163122",
          "status": "online",
          "sub_status": "active",
          "website": "https://myserviceagent.net",
          "airtime_balance": 40,
          "sms_balance": 93,
          "inbound_calls": 15,
          "outbound_calls": 14,
          "dropped_calls": 10,
          "deleted_at": null,
          "last_call": "2020-11-02 00:20:18",
          "created_at": "2020-06-11 20:23:22",
          "updated_at": "2020-07-03 19:12:58",
          "type": "profit",
          "supports_international": "yes",
          "software_developer": "no",
          "dev_platform": "no",
          "phone_verified": 0,
          "email_verified": 0,
          "country": "Nigeria",
          "otp_code": null,
          "wallet_notification": "yes",
          "autorenew": "no",
          "accepted_terms": "no"
        }
      }
    ],
    "first_page_url": "https://crm-api.myserviceagent.net/api/v1/telemarketing/queues/1?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://crm-api.myserviceagent.net/api/v1/telemarketing/queues/1?page=1",
    "next_page_url": null,
    "path": "https://crm-api.myserviceagent.net/api/v1/telemarketing/queues/1",
    "per_page": 10,
    "prev_page_url": null,
    "to": 2,
    "total": 2
  }
}

HTTP Request

GET https://api.myserviceagent.net/api/v1/telemarketing/queues/:id

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Query Parameters

Name Located in Description Required Type
id path Job Id Yes long
page formData Page number No long

Responses

Code Description
200 Response data
400 Please enter your API Key
401 Unauthorized or Invalid API key
404 No Telemarketing Jobs

Cancel a telemarketing job

When you’ve scheduled a telemarketing job, you can call this endpoint to cancel the job provided it has not been processed. This endpoint requires that you send the id value returned from the response when the job was initially scheduled.

curl --location --request GET 'https://api.myserviceagent.net/api/v1/telemarketing/queues/70/cancel' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "page" : 1
}'

require "uri"
require "net/http"

url = URI("https://api.myserviceagent.net/api/v1/telemarketing/queues/70/cancel")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"
request.body = {
  "page" : 1
}

response = https.request(request)
puts response.read_body

import requests

url = "https://api.myserviceagent.net/api/v1/telemarketing/queues/70/cancel"

payload= {
  "page" : 1
}
headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  mode: "raw",
  msisdns: "2348000000000,2348000000000",
  message_text: "Hello there",
  name: "Test job",
  run_time: "2021-12-31 23:00:00"},
});

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch(
  "https://api.myserviceagent.net/api/v1/telemarketing/queues/70/cancel",
  requestOptions
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/telemarketing/queues/70/cancel');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));
$request->setBody('{
\n    "page" : 1
\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/telemarketing/queues/70/cancel"
  method := "GET"

  payload := strings.NewReader(`{   `+"
"+`
    "page" : 1`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{
  "status":true,
  "message":"Scheduled Job cancelled"
  }

HTTP Request

GET https://api.myserviceagent.net/api/v1/telemarketing/queues/:id/cancel

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Query Parameters

Name Located in Description Required Type
id path Job Id Yes long

Responses

Code Description
201 Response data
400 Please enter your API Key
401 Unauthorized or Invalid API key
404 No Telemarketing Jobs

View single telemarketing job item status

When you’ve created a voice or SMS telemarketing job, you can utilize this endpoint to view the delivery status and additional information for a single msisdn(phone number). The id returned when the telemarketing job was initially created and a single msisdn is required as request parameters. The status field in the response applies to SMS jobs and tells you the status of the SMS sent to the supplied msisdn (phone number).

Below are the possible statuses and their meaning.

sent: The message has been sent by our system.

submitted: The message has been submitted to the MNO (Mobile network operator).

rejected: The message has been rejected by the MNO. This is a final status.

success: The message has successfully been delivered to the receiver’s handset. This is a final status.

failed: The message could not be delivered to the receiver’s handset. This is a final status.

expired: The receiver’s handset was switched off for a long period of time, and the MNO validity of the message has expired.

The job_status field in the response applies to a voice job. A value of 'success' implies the call was successfully placed. While a value of 'failed' implies the call was not successfully placed. To check actual time spent by a consumer, please refer to the duration_in_seconds field in the response.

curl --location --request POST 'https://api.myserviceagent.net/api/v1/telemarketing/jobs/85/status' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "page" : 1
}'

require "uri"
require "net/http"

url = URI("https://api.myserviceagent.net/api/v1/telemarketing/jobs/85/status")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"
request.body = {
  "page" : 1
}

response = https.request(request)
puts response.read_body

import requests

url = "https://api.myserviceagent.net/api/v1/telemarketing/jobs/85/status"

payload= {
  "page" : 1
}
headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  mode: "raw",
  msisdns: "2348000000000",
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch(
  "https://api.myserviceagent.net/api/v1/telemarketing/jobs/85/status",
  requestOptions
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/telemarketing/jobs/85/status');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));
$request->setBody('{
\n    "page" : 1
\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/telemarketing/jobs/85/status"
  method := "POST"

  payload := strings.NewReader(`{   `+"
"+`
    "page" : 1`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{"status":true,
"message":"fetched job",
"data":{
  "job_id":85,
  "status":"sent",
  "type":"sms",
  "created_at":"2022-01-27 18:17:20",
  "run_time":"2022-01-27 06:17:19",
  "local_cost":"3.5",
  "message_text":"Hello there",
  "message_audio":null,
  "msisdn":"2348000000000",
  "jobstatus":"failed",
  "cost":0
    }
      }

HTTP Request

POST https://api.myserviceagent.net/api/v1/telemarketing/jobs/85/status

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Body Parameters

Name Located in Description Required Type
id path Job Id Yes long
msisdns json body MSISDN Yes string

Responses

Code Description
201 Response data
400 Please enter your API Key
401 Unauthorized or Invalid API key
404 No Telemarketing Jobs

Get analytics for a single telemarketing job

With this endpoint, you can get key analytics for a single telemarketing job.

This endpoint requires that you send the id value returned from the response when the job was initially created or scheduled as a path parameter.

You can also get the id value when you call the Get all Telemarketing Jobs endpoint.

Response guide

totalProcessed key represents the total number of recipients associated with the telemarketing job

success key represents the number of messages delivered successfully or the number of calls placed successfully in the case of a voice telemarketing job.

pending key represents the number of messages not yet delivered or number of calls not yet placed successfully in the case of a voice telemarketing job.

successRatePercentage key returns the message delivery rate in percentage or the pickup rate in percentage in the case of a voice telemarketing job.

curl --location -g --request GET 'https://api.myserviceagent.net/api/v1/telemarketing/analytics/3093' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw ''

The above command returns JSON structured like this:

{
 "status": true,
  "message": "Success",
  "data": {
    "totalProcessed": 2,
    "success": 2,
    "pending": 0,
    "successRatePercentage": "100.00",
    "job": {
      "id": 3093,
      "name": "test",
      "client_id": 111,
      "message_audio": "https://crm-api.myserviceagent.net/uploads/telejobs/audio/111--1660580537.wav",
      "status": "new",
      "message_text": null,
      "run_time": "2022-08-15 17:22:17",
      "deleted_at": null,
      "created_at": "2022-08-15 17:22:17",
      "updated_at": "2022-08-15 17:22:17",
      "type": "voice",
      "sender_id": null,
      "webhook_url": null,
      "calculatedCost": 44,
      "reciepentsno": 2,
      "cost": "calculated"
    }
}

HTTP Request

GET https://api.myserviceagent.net/api/v1/telemarketing/analytics/:id

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Query Parameters

Name Located in Description Required Type
id path Job Id Yes long

Survey & IVR APIs

The survey and IVR APIs enable you to trigger preset and standardized surveys and IVR flows to one or more phone numbers and also get analytics and responses for the triggered surveys and IVR flows. Please contact us via hello@myserviceagent to configure more specific survey flows that might better suit your needs.

Trigger a voice survey or IVR job

With this endpoint, you can instantly send a voice survey to up to 1000 phone numbers per request.

The identifier field which identifies a preset voice survey flow is required. It can be a generic flow or a flow specially designed for you. Please contact us via hello@myserviceagent to configure survey flows tailored to your needs and get a survey identifier.

A name field is also required to reference a survey job.

An intro_audio file parameter in wav, gsm or mp3 format may be optionally sent. This message is played to the respondent before they start responding to the standard survey questions or IVR menu.

curl --location --request POST 'https://api.myserviceagent.net/api/v1/survey'
--header 'Authorization: Bearer <YOUR_API_KEY>' \

--form 'msisdns="08000000000"',
--form 'identifier="demo"',
--form 'name="Test job22"'
--form 'intro_audio=@"/C:/Users/IT/Downloads/survey_audio.mp3"'
--form 'webhook_url="https://your-webhook-url"'

require "uri"
require "net/http"

url = URI("https://api.myserviceagent.net/api/v1/survey")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"
request.body = {
"msisdns": "08000000000",
"identifier" : "demo",
"name": "Test job22"
"intro_audio": "/C:/Users/IT/Downloads/survey_audio.mp3"'
"webhook_url":"https://your-webhook-url"
}

response = https.request(request)
puts response.read_body

import requests

url = "https://api.myserviceagent.net/api/v1/survey"

payload = {
"msisdns": "2348000000000",
"identifier" : "demo",
"name": "Test job22"

}
files=[
  ('intro_audio',('survey_intro.mp3',open('/C:/Users/IT/Downloads/survey_intro.mp3','rb'),'audio/mpeg'))
]
headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload,files=files)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");


var formData = new FormData();
formData.append("name", "Testing again");
formData.append("identifier", "demo");
formData.append("msisdns", "2348000000000");
formData.append("intro_audio", fileInput.files[0],
  "/C:/Users/IT/Downloads/NewVoiceTelemarketingAudio.mp3");
formData.append("webhook_url", "https://your-webhook-url");
var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: formData,
  redirect: "follow",
};

fetch(
  "https://api.myserviceagent.net/api/v1/survey",
  requestOptions
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/survey');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));
$request->setBody('{
"msisdns": "2348000000000",
"identifier" : "demo",
"name": "Test job22",
"webhook_url":"https://your-webhook-url"
}');
$request->addUpload('intro_audio', '/C:/Users/IT/Downloads/survey_audio.mp3'');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
    "path/filepath"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/survey"
  method := "POST"

  payload := &bytes.Buffer{}
   writer := multipart.NewWriter(payload)
  _ = writer.WriteField("name", "Testing again")
  _ = writer.WriteField("msisdns", "+2348000000001")
  file, errFile3 := os.Open("/C:/Users/IT/Downloads/survey_intro.mp3")
  defer file.Close()
  part3,
         errFile3 := writer.CreateFormFile("intro_audio",filepath.Base("/C:/Users/IT/Downloads/survey_intro.mp3"))
  _, errFile3 = io.Copy(part3, file)
  if errFile3 != nil {
    fmt.Println(errFile3)
    return
  }
  _ = writer.WriteField("identifier", "demo")
  err := writer.Close()
  if err != nil {
    fmt.Println(err)
    return
  }

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{
  "status":true,
  "message":"Done",
  "data":{
    "name":"Testing again",
    "client_id":12,
    "identifier":"demo",
    "msisdns":"2348000000000",
    "run_time":"2022-02-05 08:24:39",
    "updated_at":"2022-02-05 20:24:39",
    "created_at":"2022-02-05 20:24:39",
    "id":3,
    "reciepentsno":1,
    "cost":"calculated"
    }
  }

HTTP Request

POST https://api.myserviceagent.net/api/v1/survey

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Body Parameters

Name Located in Description Required Type
msisdns formData MSISDN Yes string
identifier formData Identifies a preset survey flow Yes string
name formData Name of survey job Yes string
intro_audio formData Survey intro audio file Yes file

Responses

Code Description
200 Response data
400 Please enter your API Key
401 Unauthorized or Invalid API key
404 No Telemarketing Jobs

View survey responses

When you’ve sent out one or more survey jobs for a survey identifier, you can utilize this endpoint to view the responses associated with the survey identifier. ​​ Voice responses are transcribed into text. This endpoint requires the survey identifier parameter. The data returned is paginated.

curl --location --request POST 'https://api.myserviceagent.net/api/v1/survey/responses'
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "page" : 1
}'

require "uri"
require "net/http"

url = URI("https://api.myserviceagent.net/api/v1/survey/responses")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"
request.body = {
  "page" : 1
}

response = https.request(request)
puts response.read_body

import requests

url = "https://api.myserviceagent.net/api/v1/survey/responses"

payload= {
  "page" : 1
}
headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  mode: "raw",
  identifier: "Demo message",
  page: 2,
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch(
  "https://api.myserviceagent.net/api/v1/survey/responses",
  requestOptions
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/survey/responses');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));
$request->setBody('{
\n    "page" : 1
\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/survey/responses"
  method := "POST"

  payload := strings.NewReader(`{   `+"
"+`
    "page" : 1`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{"status":true,
"message":"Voice survey sent",
"data":{
  "current_page":2,
  "data":[
    {"id":1,
    "continuetext":"1",
    "love":"everything",
    "improve":" ",
    "feature":" nope",
    "goal":" yes",
    "achievegoal":"",
    "schedulecall":" 2",
    "schedule":" ",
    "rating":" 4",
    "suggest":" ",
    "phone":"08133150074",
    "schedulestatus":"new",
    "call_time":"2022-01-28 08:45:12",
    "schedule_time":"2022-01-28 09:45:12",
    "duration":5}
    ],
    "first_page_url":"https://api.myserviceagent.net/api/v1/survey/responses?page=1",
    "from":16,
    "last_page":2,
    "last_page_url":"https://api.myserviceagent.net/api/v1/survey/responses?page=2",
    "next_page_url":null,
    "path":"https://api.myserviceagent.net/api/v1/survey/responses",
    "per_page":15,
    "prev_page_url":"https://api.myserviceagent.net/api/v1/survey/responses?page=1/",
    "to":16,
    "total":16
    }
    }

HTTP Request

POST https://api.myserviceagent.net/api/v1/survey/responses

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Body Parameters

Name Located in Description Required Type
identifier json body Identifies a preset survey flow Yes string
page json body Page number for Pagination Yes long

Responses

Code Description
200 Response data
400 Please enter your API Key
401 Unauthorized or Invalid API key
404 No Telemarketing Jobs

View survey summary

When you’ve sent out one or more survey jobs for a survey identifier, you can utilize this endpoint to view the summary and key statistics of the responses associated with the survey identifier. This endpoint requires the survey identifier parameter

curl --location --request POST 'https://api.myserviceagent.net/api/v1/survey/summary'
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "page" : 1
}'

require "uri"
require "net/http"

url = URI("https://api.myserviceagent.net/api/v1/survey/summary")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"
request.body = {
  "page" : 1
}

response = https.request(request)
puts response.read_body

import requests

url = "https://api.myserviceagent.net/api/v1/survey/summary"

payload= {
  "page" : 1
}
headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  mode: "raw",
  identifier: "Demo message",
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch(
  "https://api.myserviceagent.net/api/v1/survey/summary",
  requestOptions
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/survey/summary');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));
$request->setBody('{
\n    "page" : 1
\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/survey/summary"
  method := "POST"

  payload := strings.NewReader(`{   `+"
"+`
    "page" : 1`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{
"status":true
"message":"Fetched results"
"data": {
"satisfiedCustomerNumber":2
"unsatisfiedCustomerNumber":0
"respondedToCSATQuestion":2
"CSAT":100
"spentOneOrMoreSeconds":6
"averageDurationInSeconds":"5.3333"
"pickUpRateInPercentage":38
  }
}

HTTP Request

POST https://api.myserviceagent.net/api/v1/survey/summary

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Body Parameters

Name Located in Description Required Type
identifier json body Identifies a preset survey flow Yes string

Responses

Code Description
200 Response data
400 Please enter your API Key
401 Unauthorized or Invalid API key
404 No Telemarketing Jobs

OTP APIs

The OTP APIs enable you to add user verification to your web applications. The APIs allow you to deliver One-time passwords(OTPs) via SMS or Voice calls to a phone number and also verify the OTPs.

Initiate a Voice OTP Request

With this endpoint, you can send an OTP as a voice call to a phone number.

curl --location --request POST 'https://api.myserviceagent.net/api/v1/otp/voice' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "msisdn" : "+2348000000001",
    "length" : 6,
    "expires" : 40,
    "alphanumeric" : true
}'

require "uri"
require "net/http"

url = URI("https://api.myserviceagent.net/api/v1/otp/voice")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"
request.body = "{\r\n    \"msisdn\" : \"+2348000000001\",\r\n    \"length\" : 6,\r\n    \"expires\" : 40,\r\n    \"alphanumeric\" : true\r\n}"

response = https.request(request)
puts response.read_body

import requests

url = "https://api.myserviceagent.net/api/v1/otp/voice"

payload={
  "msisdn" : "+2348000000001",
  "length" : 6,
  "expires" : 40,
  "alphanumeric" : True
}
headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  msisdn: "+2348000000001",
  length: 6,
  expires: 40,
  alphanumeric: true,
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.myserviceagent.net/api/v1/otp/voice", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));



<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/otp/voice');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));
$request->setBody('{
\n    "msisdn" : "+2348000000001",
\n    "length" : 6,
\n    "expires" : 40,
\n    "alphanumeric" : true
\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/otp/voice"
  method := "POST"

  payload := strings.NewReader(`{`+"
"+`
    "msisdn" : "+2348000000001",`+"
"+`
    "length" : 6,`+"
"+`
    "expires" : 40,`+"
"+`
    "alphanumeric" : true`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{
  "status": true,
  "message": "OTP sent to msisdn",
  "otp": {
    "type": "voice",
    "expires_at": "2020-12-23T16:32:01.466915Z",
    "status": "new",
    "deliverystatus": "sent",
    "generated_by": "Client",
    "msisdn": "+2348000000001",
    "message": null,
    "webhook_url": "https://webhook.site/7a8061f5-588b-4623-83cc-05cc4637bc44",
    "client_id": 38,
    "updated_at": "2020-12-23 16:52:01",
    "created_at": "2020-12-23 16:52:01",
    "id": 1
  }
}

Response guide:

Key Description
id Unique identifier for the voice otp
client_id Your account id
msisdn The phone number the OTP was sent to
type Type of OTP. Will always resolve to "voice" in this case
expires_at Time the OTP expires. It is a function of the "expires" parameter
status Current status of the OTP. Initially has a value of "new". It will resolve to "verified" if the otp becomes verified or "expired" if it becomes expired before verification
created_at Time the OTP record was created
updated_at Time the OTP record was last updated
message Message sent to the user. Only used for OTP with custom message
webhook_url Webhook url for success notification
generated_by Who generated the OTP. Will resolve to "Client" if you specified the OTP in the original request or "Provider" otherwise
deliverystatus Delivery status of the OTP. Initially has a value of "sent" Will resolve to "success" if the otp becomes delivered

HTTP Request

POST https://api.myserviceagent.net/api/v1/otp/voice

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Body Parameters

Name Located in Description Required Type
msisdn json body MSISDN Yes string
otp json body OTP to be sent to MSISDN No long
length json body Optionally specify the length of the generated OTP. Only valid when the otp parameter is not included. Value must be one of 4, 5, 6, 7 or 8. No long
expires json body Optionally specify how long the generated otp will be valid for in minutes. Default is 10 minutes. No long
alphanumeric json body Optionally specify if the otp should be alphanumeric. Only valid when the otp parameter is not included.Value must be true or false. Defaults to false when the parameter is not included. No boolean
message json body Optionally specify a custom message to be sent to the msisdn. Pease make sure to include the OTP in the message content. No boolean
webhook_url json body Optionally specify a webhook url for success notification No string

Responses

Code Description
200 Successful - Response data
400 Bad Request
401 Unauthorized API key
405 Invalid input

Initiate an SMS OTP Request

With this endpoint, you can send an OTP via SMS to a phone number.

curl --location --request POST 'https://api.myserviceagent.net/api/v1/otp/sms' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "msisdn" : "+2348000000001",
    "length" : 6,
    "expires" : 40,
    "alphanumeric" : true
}'

require "uri"
require "net/http"

url = URI("https://api.myserviceagent.net/api/v1/otp/sms")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"
request.body = "{\r\n    \"msisdn\" : \"+2348000000001\",\r\n    \"length\" : 6,\r\n    \"expires\" : 40,\r\n    \"alphanumeric\" : true\r\n}"

response = https.request(request)
puts response.read_body

import requests

url = "https://api.myserviceagent.net/api/v1/otp/sms"

payload={
  "msisdn" : "+2348000000001",
  "length" : 6,
  "expires" : 40,
  "alphanumeric" : True
}
headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  msisdn: "+2348000000001",
  length: 6,
  expires: 40,
  alphanumeric: true,
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.myserviceagent.net/api/v1/otp/sms", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/otp/sms');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));
$request->setBody('{
\n    "msisdn" : "+2348000000001",
\n    "length" : 6,
\n    "expires" : 40,
\n    "alphanumeric" : true
\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

The above command returns JSON structured like this:

{
  "status": true,
  "message": "OTP sent to msisdn",
  "otp": {
    "type": "sms",
    "expires_at": "2020-12-23T16:34:17.270727Z",
    "status": "new",
    "msisdn": "+2348000000001",
    "client_id": 38,
    "updated_at": "2020-12-23 16:54:17",
    "created_at": "2020-12-23 16:54:17",
    "id": 2
  }
}

HTTP Request

POST https://api.myserviceagent.net/api/v1/otp/sms

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string

Body Parameters

Name Located in Description Required Type
msisdn json body MSISDN Yes string
otp json body OTP to be sent to MSISDN No long
length json body Optionally specify the length of the generated OTP. Only valid when the otp parameter is not included. Value must be one of 4, 5, 6, 7 or 8. No long
expires json body Optionally specify how long the generated otp will be valid for in minutes. Default is 10 minutes. No long
alphanumeric json body Optionally specify if the otp should be alphanumeric. Only valid when the otp parameter is not included.Value must be true or false. Defaults to false when the parameter is not included. No boolean
message json body Optionally specify a custom message to be sent to the msisdn. If you send this parameter and do not include the otp in your custom message, you must set the append_otp_to_message parameter to be true. No boolean
append_otp_to_message json body Optionally specify if the otp should be appended to your custom message. This should be used when the message parameter is sent. Value must be true or false. Defaults to false when the parameter is not included. No boolean
sender_id json body Optionally specify a sender id to be used to deliver the otp. The sender id must have been registered and approved on your MyserviceAgent dashboard. When not sent, a generic sender id will be used to deliver the otp. This only works for local(Nigerian) numbers at the moment. No string

Responses

Code Description
200 Successful - Response data
400 Bad Request
401 Unauthorized API key
405 Invalid input

Initiate a WhatsApp OTP Request

With this endpoint, you can send an OTP via WhatsApp to a phone number registered on WhatsApp.

curl --location --request POST `https://api.myserviceagent.net/api/v1/otp/whatsapp` \

--header 'Authorization: Bearer {{API_KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "msisdn": "+2349111222333",
    "otp": "1012JK"
}'

The above command returns JSON structured like this:

{
  "status": true,
  "message": "OTP sent to msisdn",
  "otp": {
    "type": "whatsapp",
    "expires_at": "2022-11-07T19:09:17.705625Z",
    "status": "success",
    "local_cost": "3.5",
    "session_id": 356089,
    "msisdn": "+2349111222333",
    "generated_by": "Client",
    "message": null,
    "client_id": 12,
    "updated_at": "2022-11-07 19:59:17",
    "created_at": "2022-11-07 19:59:17",
    "id": 46,
    "deliverycost": "10"
  }
}

Header Request

POST https://api.myserviceagent.net/api/v1/otp/whatsapp

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key yes string

Body Parameters

Name Located in Description Required Type
msisdn json body MSISDN yes string
otp json body OTP to be sent to MSISDN no long
length json body Optionally specify the length of the generated OTP. Only valid when the otp parameter is not included. Value must be one of 4, 5, 6, 7 or 8. no long
expires json body Optionally specify how long the generated otp will be valid for in minutes. Default is 10 minutes. no long
alphanumeric json body Optionally specify if the otp should be alphanumeric. Only valid when the otp parameter is not included.Value must be true or false. Defaults to false when the parameter is not included. no boolean

Responses

Code Description
200 Successful - Response data
400 Bad Request
401 Unauthorized API key
405 Invalid input

Verify an OTP Request

When an OTP has been sent to a phone number via the voice or SMS channel, you may utilize this endpoint to verify the OTP.

curl --location --request POST 'https://api.myserviceagent.net/api/v1/otp/verify' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "msisdn" : "+2348000000001",
    "otp" : "12345"
}'

require "uri"
require "net/http"

url = URI("https://api.myserviceagent.net/api/v1/otp/verify")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"
request.body = "{\r\n    \"msisdn\" : \"+2348000000001\",\r\n    \"otp\" : \"12345\"\r\n}"

response = https.request(request)
puts response.read_body

import requests

url = "https://api.myserviceagent.net/api/v1/otp/verify"

payload={
  "msisdn" : "+2348000000001",
  "otp" : "12345"
}
headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({ msisdn: "+2348000000001", otp: "12345" });

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.myserviceagent.net/api/v1/otp/verify", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/otp/verify"
  method := "POST"

  payload := strings.NewReader(`{`+"
"+`
    "msisdn" : "+2348000000001",`+"
"+`
    "otp" : "12345"`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{
  "status": false,
  "error": "OTP does not exist"
}

HTTP Request

POST https://api.myserviceagent.net/api/v1/otp/verify

Header Parameters

Name Located in Description Required Type
authorization header Enter your generated API key Yes string

Body Parameters

Name Located in Description Required Type
msisdn formData MSISDN to verify Yes string
otp formData OTP to verify Yes string

Responses

Code Description
200 Successful - Response data
400 Bad Request
401 Unauthorized API key
405 Invalid input

Account APIs

The account APIs enable you to get information about your account programmatically.

Get Account summary

With this endpoint, you can get basic information about your account

curl --location --request GET 'https://api.myserviceagent.net/api/v1/clients/counts/summary' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \


require "uri"
require "net/http"

url = URI("https://api.myserviceagent.net/api/v1/clients/counts/summary")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"


response = https.request(request)


import requests

url = "https://api.myserviceagent.net/api/v1/clients/counts/summary"


headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");



var requestOptions = {
  method: "GET",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.myserviceagent.net/api/v1/clients/counts/summary", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));



<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/clients/counts/summary');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));

try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/clients/counts/summary"
  method := "GET"



  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{
  "status": true,
  "message": "Summary fetched successfully",
  "data": { "total_funded": "20014",
  "total_units_spent": "1716",
  "balance": "18298",
  "name": "Cadbury Plc",
  "client_id": "12",
  "email": "josholatunde@gmail.com",
  "phone_number": "2348133150074",
  "contact_person": "Josh Ola",
  "date_joined": "15 Nov 2020"
  }
}

HTTP Request

GET https://api.myserviceagent.net/api/v1/clients/counts/summary

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string
Content-Type header application/json Yes string

Response guide

total_funded key represents the total amount you've funded your account with since you signed up.

total_units_spent key represents the total units you've expended since you signed up

balance key represents your total current available unit.

name key returns the business or organization name

contact_person key returns the contact person attached to the account

date_joined key returns the date the account was created

Responses

Code Description
200 Successful - Response data
400 Bad Request
401 Unauthorized API key
405 Invalid input

Get conversions

Get default values and equivalent unit for USD and NGN

If none of the amount and currency parameters are sent, the endpoint returns only minimum_amount_naira and minimum_amount_dollar props.

To fetch the unit equivalent of a potential purchase, please send the amount and currency query params.

currency can be either USD or NGN

If the amount query param is sent, then the currency param is required and vice-versa.

curl --location --request GET 'https://api.myserviceagent.net/api/v1/clients/counts/summary' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \


require "uri"
require "net/http"

url = URI("https://api.myserviceagent.net/api/v1/clients/counts/summary")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"


response = https.request(request)


import requests

url = "https://api.myserviceagent.net/api/v1/clients/counts/summary"


headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");



var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.myserviceagent.net/api/v1/clients/counts/summary", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));



<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/clients/counts/summary');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));

try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/clients/counts/summary"
  method := "GET"



  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{
  "status": true,
  "message": "Summary fetched successfully",
  "data": {   "minimum_amount_naira": "2000",
    "minimum_amount_dollar": "4.58"
  }
}

HTTP Request

GET https://api.myserviceagent.net/api/v1/conversion?amount=5&currency=USD

Params

amount 5

currency USD

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string
Content-Type header application/json Yes string

Get phone numbers

With this endpoint, you can get all the phone numbers associated with your account. You can use any of the phone numbers when calling the create a voice telemarketing job endpoint

curl --location --request GET 'https://api.myserviceagent.net/api/v1/clients/clients/phones' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \


require "uri"
require "net/http"

url = URI("https://api.myserviceagent.net/api/v1/clients/clients/phones")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"


response = https.request(request)


import requests

url = "https://api.myserviceagent.net/api/v1/clients/clients/phones"


headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");



var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.myserviceagent.net/api/v1/clients/clients/phones", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));



<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.myserviceagent.net/api/v1/clients/clients/phones');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Bearer <YOUR_API_KEY>',
  'Content-Type' => 'application/json'
));

try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.myserviceagent.net/api/v1/clients/clients/phones"
  method := "GET"



  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

The above command returns JSON structured like this:

{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "client_id": "12",
      "phone_number": "2348000000000",
      "status": "verified",
      "created_at": "2023-02-17 14:07:42",
      "updated_at": null
    },
    {
      "id": 2,
      "client_id": "12",
      "phone_number": "2348000000001",
      "status": "verified",
      "created_at": "2023-02-17 14:07:53",
      "updated_at": null
    }
  ],
  "first_page_url": "http://localhost:8000/api/v1/clients/phones?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "http://localhost:8000/api/v1/clients/phones?page=1",
  "next_page_url": null,
  "path": "http://localhost:8000/api/v1/clients/phones",
  "per_page": 15,
  "prev_page_url": null,
  "to": 2,
  "total": 2
}

HTTP Request

GET https://api.myserviceagent.net/api/v1/clients/phones

Header Parameters

Name Located in Description Required Type
Authorization header Enter your generated API key Yes string
Content-Type header application/json Yes string

Webhooks

You can utilize the MyServiceAgent webhook mechanism to notify your application anytime there’s an update on some of your requests.

For instance, you can specify a URL via the webhook_url parameter when you create a voice telemarketing job and MyServiceAgent will send you webhook notifications when the call ends for each of the phone numbers associated with the telemarketing job.

Voice Telemarketing Job Webhook

When you’ve placed a call to some numbers using the voice telemarketing job endpoint and specify a webhook URL via the webhook_url parameter, we will send the following request to your webhook URL for calls that are successful.

HTTP Request

Webhook Payload
POST webhook_url | application/json
{
"id": 57208,
"name": "test",
"client_id": 111,
"job_id": 4584,
"message_audio": null,
"message_text": "Hello to you too",
"msisdn": "+2348000000000",
"run_time": "2022-12-01 02:29:33",
"created_at": "2022-12-01 02:29:34",
"updated_at": "2022-12-01 02:29:46",
"duration_in_seconds": 4,
"cost": 22,
"type": "voice",
"external_id": "91b49feb-4642-5b6b-911f-4c874e202d8b",
"jobstatus": "success"

}

Responses

Code Description
200 Successful - Response data
400 Bad Request
401 Unauthorized API key
405 Invalid input

Voice OTP Webhook

When you’ve initiated a voice OTP and specify a webhook URL via the webhook_url parameter, we will send the following request to your webhook URL for calls that are successful.

HTTP Request

Webhook Payload
POST webhook_url | application/json
{
"id": 57208,
"client_id": 111,
"msisdn": "+2348000000000",
"type": "voice",
"expires_at": "2022-12-01 02:39:34",
"created_at": "2022-12-01 02:29:34",
"updated_at": "2022-12-01 02:29:46",
"message": null,
"duration_in_seconds": 4,
"ussd_suffix_code": null,
"generated_by": "Client",
"deliverystatus": "success"

}

Response guide

Key Description
id Unique identifier for the voice otp
client_id Your account id
msisdn The phone number the OTP was sent to
type Type of OTP. Will always resolve to "voice" in this case
expires_at Time the OTP expires
created_at Time the OTP record was created
updated_at Time the OTP record was last updated
message Message sent to the user. Only used for OTP with custom message
duration_in_seconds Duration of the call in seconds
ussd_suffix_code USSD suffix code. Only used for USSD OTP
generated_by Who generated the OTP. Will resolve to "Client" if you specified the OTP in the original request or "Provider"
deliverystatus Delivery status of the OTP. Will always resolve to "success" in this case

Survey Job Webhook

When you’ve placed a call to some numbers using the Survey job endpoint and specify a webhook URL via the webhook_url parameter, MyServiceAgent will send the following request to your webhook URL for calls that are successful.

HTTP Request

Webhook Payload
POST webhook_url | application/json
{
"id": 35,
"name": "Testing again with",
"identifier": "from-tango",
"client_id": 111,
"job_id": 35,
"msisdn": "2348000000000",
"run_time": "2022-06-28 06:16:26",
"created_at": "2022-06-28 18:16:26",
"updated_at": "2022-06-28 18:16:26",
"duration_in_seconds": 12,
"intro_audio": "https://api.myserviceagent.net/somepath/test.wav",
"jobstatus": "success",
"cost": 22
}

Responses

Code Description
200 Successful - Response data
400 Bad Request
401 Unauthorized API key
405 Invalid input

Errors

The MyServiceAgent API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many resources! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
shell ruby python javascript java go php