NAV Navbar
Channels logo
http

Overview

This describes the resources that make up the official Channels App REST API. If you have any problems or requests please chat with us or send an email at [email protected] - we’re there for you 24/7.

Errors

Example request:

PUT /api/v1/users/1234567/disable HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 20

[ "USER_NOT_EXIST" ]

Channels App uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with our servers (these are rare).

Error Code Meaning
400 Bad Request – There was something wrong with your request
401 Unauthorized – Your API key is wrong
403 Forbidden – You don’t have permissions to access this resource
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access data with an invalid method
406 Not Acceptable – You requested a format that isn’t json
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.


In addition, in response body we send an array of error codes, which describe what went wrong.

Authentication

Example of authenticated request:

GET /api/v1/path/to/resource HTTP/1.1
x-api-token: your-secret-api-key
Account: abcdef
Host: api.channels.app

When using API, you have to authenticate your requests using an API key. You can generate one in the developer’s section of our application. It represents your account, so you should keep it secret!


Also you need to include an Account header in all your requests. You can see your account’s name in developer’s section.


Header Description
x-api-token Your secret api key generated from app.channels.app page
Account Your account identifier

Convention

All request parameters (query string) are optional unless stated otherwise.

Users

Every operation in Channels App is performed by users or on behalf of users. User can be assigned different roles, and roles can have various permissions.

Retrieve all users

Example request:

GET /api/v1/users HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 463

[ {
  "id" : 59,
  "username" : "[email protected]",
  "name" : "John",
  "surname" : "Doe",
  "roleId" : 59,
  "role" : "Owner",
  "enabled" : true,
  "doNotAcceptIncomingCalls" : false,
  "missedIncomingCallsNotification" : false,
  "msisdns" : [ ],
  "state" : "ACTIVE"
}, {
  "id" : 2575634082126999075,
  "username" : "[email protected]",
  "roleId" : 59,
  "role" : "Owner",
  "privatePhoneNumber" : null,
  "msisdns" : [ ],
  "state" : "PENDING"
} ]

You can get all users assigned to your account as list.

Response results
Path Type Description
[] Array All active users
[].id Number User’s id
[].username String User’s username (typically email)
[].name String Name given in registration
[].surname String Surname given in registration
[].roleId Number Id which identify user’s role
[].role String Role name
[].enabled Boolean Detect if user is enabled. Empty if state = PENDING
[].state String Current user’s state
[].doNotAcceptIncomingCalls Boolean Boolean flag determining whether user is blocking incoming calls
[].missedIncomingCallsNotification Boolean If true user will receive email notifications about missed calls
[].privatePhoneNumber Null User’s phone number added on account registration
[].msisdns Array List of numbers assigned to user



With this request you will also receive invited users. They will only have username (email to which you sent invitation), roleId, role (name of a given role) and current state (always PENDING).


User states

State Description
ACTIVE User is enabled (can make calls, counts in plan’s limit)
INACTIVE User disabled (cannot login into your account)
PENDING User was invited via email, but hasn’t registered yet

Checking user’s existence

Example request:

GET /api/v1/users/exists?email=john.doe%40example.com HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 21

{
  "exists" : true
}

You can easily check whether user exists by passing email.

Request parameters
Parameter Description
email (required) User’s email to check


Possible errors
Error key Description
PARAMETER.NOT_PRESENT When email was not present

Disable user

Example request:

PUT /api/v1/users/64/disable HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 158

{
  "id" : 64,
  "username" : "[email protected]",
  "name" : "John",
  "surname" : "Doe",
  "role" : "User",
  "enabled" : false,
  "state" : "INACTIVE"
}

You can disable other users - they will be unable to login to your account and to make calls. In addition, they will stop counting towards your plan’s limit.

/api/v1/users/{userId}/disable

Parameter Description
userId User’s id to disable


You cannot disable youreself!


Possible errors
Error key Description
SELF_DISABLE When you try to disable yourself
USER_NOT_EXIST User with given id doesn’t exists

Enable user

Example request:

PUT /api/v1/users/61/enable HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 155

{
  "id" : 61,
  "username" : "[email protected]",
  "name" : "John",
  "surname" : "Doe",
  "role" : "User",
  "enabled" : true,
  "state" : "ACTIVE"
}

You can enable disabled users - they will be able to login to your account and to make calls.

/api/v1/users/{userId}/enable

Parameter Description
userId User’s id to enable


Remember that users will be counting towards your plan’s limit. If you reached limit, you will get 400 error with key
USERS.LIMIT_REACHED


Possible errors
Error key Description
USERS.LIMIT_REACHED When your plan doesn’t allow more users
USER_NOT_EXIST User with given id doesn’t exists

Number of users

Example request:

GET /api/v1/users/stats HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 62

{
  "activeCount" : 1,
  "limit" : 100,
  "pendingCount" : 5
}

You can get number of users and current user limit in your plan. Remember - you can always disable and enable them.

Response results
Path Type Description
activeCount Number Number of active users
limit Number All users limit (depends on current plan)
pendingCount Number Number of pending users (invited, but not registered)

Contacts

Contact is a basic object representing entity that you can call to.

Get all contacts

Example request:

GET /api/v1/contacts?page=2&limit=2&modificationDateFrom=2013-05-03T20%3A30%3A40.100Z&orderModificationDate=asc&msisdn=%2B HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1642

{
  "total" : 6,
  "totalPages" : 3,
  "links" : {
    "first" : "https://api.channels.app/api/v1/contacts",
    "prev" : "https://api.channels.app/api/v1/contacts?page=1",
    "next" : "https://api.channels.app/api/v1/contacts?page=3",
    "last" : "https://api.channels.app/api/v1/contacts?page=3"
  },
  "data" : [ {
    "id" : 76,
    "firstName" : null,
    "lastName" : null,
    "company" : null,
    "externalLink" : null,
    "externalOrderLink" : null,
    "createdAt" : "2022-09-28T12:43:38.000+00:00",
    "lastModificationDate" : "2022-09-28T12:43:38.489+00:00",
    "source" : "API",
    "email" : null,
    "alternativeMsisdns" : [ "+14153661222" ],
    "details" : { },
    "externalServices" : {
      "recordId" : 76,
      "pipedrivePersonId" : null,
      "pipedriveDealId" : null,
      "shopifyCustomerId" : null,
      "shoperClientId" : null,
      "shoperOrderClientId" : null,
      "hubspotContactId" : null,
      "zendeskEndUserId" : null
    }
  }, {
    "id" : 79,
    "firstName" : null,
    "lastName" : null,
    "company" : null,
    "externalLink" : null,
    "externalOrderLink" : null,
    "createdAt" : "2022-09-28T12:43:39.000+00:00",
    "lastModificationDate" : "2022-09-28T12:43:38.523+00:00",
    "source" : "API",
    "email" : null,
    "alternativeMsisdns" : [ "+33980091888" ],
    "details" : { },
    "externalServices" : {
      "recordId" : 79,
      "pipedrivePersonId" : null,
      "pipedriveDealId" : null,
      "shopifyCustomerId" : null,
      "shoperClientId" : null,
      "shoperOrderClientId" : null,
      "hubspotContactId" : null,
      "zendeskEndUserId" : null
    }
  } ]
}

Returns paginated list of contacts imported to the application.

Request parameters
Parameter Description
page Page number to be returned. Default of 1
limit Returned page will consist of that many elements or default of 100, whichever is lower
orderModificationDate Sorting applied to result, using contact’s last modification date. Either asc or desc, default asc
modificationDateFrom Filter result to only records newer or equal to given date. (e.g. 2013-05-03T20:30:40.100Z)
msisdn Filter result to records which MSISDN contains given sequence. Note: Please remember that ‘+’ is a special character in URL and make sure that you use ‘%2B’ instead. (e.g. %2B1 will show all numbers from U.S., Canada and other NANP countries.)


Response results
Path Type Description
total Number Total elements count returned by the query
totalPages Number Total pages count
links.first String API URL to first page of the data set
links.prev String API URL to prev page of the data set, or null if current is first
links.next String API URL to next page of the data set, or null if current is last
links.last String API URL to last page of the data set, or null if no data
data Array Array of contacts
data.[].id Number ID of the contact
data.[].alternativeMsisdns Array Msisdns associated with the contact
data.[].firstName String FirstName associated with the contact
data.[].lastName String Last name associated with the contact
data.[].company String Company associated with the contact
data.[].externalLink String External link related to the contact
data.[].email String Email associated with the contact
data.[].createdAt String Date when contact was created
data.[].lastModificationDate String Contact’s last modification date
data.[].externalServices Object External services data
data.[].externalServices.recordId Number id of contact


Possible errors
Error key Description
PAGE_NUMBER_INVALID When page parameter was invalid
LIMIT_INVALID When limit parameter was invalid
ORDER_MODIFICATION_DATE_INVALID When orderModificationDate parameter was invalid
MODIFICATION_DATE_FROM_INVALID When modificationDateFrom parameter was invalid

Get contact by id

Returns specific contact

Example request:

GET /api/v1/contacts/64 HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 613

{
  "id" : 64,
  "firstName" : null,
  "lastName" : null,
  "company" : null,
  "externalLink" : null,
  "externalOrderLink" : null,
  "createdAt" : "2022-09-28T12:43:38.000+00:00",
  "lastModificationDate" : "2022-09-28T12:43:37.818+00:00",
  "source" : "API",
  "email" : null,
  "alternativeMsisdns" : [ "+14153661222" ],
  "details" : { },
  "externalServices" : {
    "recordId" : 64,
    "pipedrivePersonId" : null,
    "pipedriveDealId" : null,
    "shopifyCustomerId" : null,
    "shoperClientId" : null,
    "shoperOrderClientId" : null,
    "hubspotContactId" : null,
    "zendeskEndUserId" : null
  }
}

/api/v1/contacts/{contactId}

Parameter Description
contactId Contacts’s id to get
Response results
Path Type Description
id Number ID of the contact
alternativeMsisdns Array Msisdns associated with the contact
firstName String FirstName associated with the contact
lastName String Last name associated with the contact
company String Company associated with the contact
externalLink String External link related to the contact
email String Email associated with the contact
createdAt String Date when contact was created
lastModificationDate String Contact’s last modification date
externalServices Object External services data
externalServices.recordId Number id of contact


Possible errors
Error key Description
RESOURCE_NOT_FOUND When contact doesn’t exist

Edit contact by id

Edits contact by id.

Example request:

POST /api/v1/contacts/38 HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app
Content-Length: 379

{
  "id" : null,
  "firstName" : "Jeo",
  "lastName" : "Doe",
  "company" : "[email protected]",
  "externalLink" : "https://www.crazycall.com",
  "externalOrderLink" : "https://www.crazycall.com",
  "createdAt" : null,
  "lastModificationDate" : null,
  "source" : null,
  "email" : "[email protected]",
  "alternativeMsisdns" : null,
  "details" : null,
  "externalServices" : null
}

/api/v1/contacts/{contactId}

Parameter Description
contactId Contacts’s id which details will be updated
Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 670

{
  "id" : 38,
  "firstName" : "Jeo",
  "lastName" : "Doe",
  "company" : "[email protected]",
  "externalLink" : "https://www.crazycall.com",
  "externalOrderLink" : "https://www.crazycall.com",
  "createdAt" : "2022-09-28T12:43:36.000+00:00",
  "lastModificationDate" : "2022-09-28T12:43:36.117+00:00",
  "source" : "API",
  "email" : "[email protected]",
  "alternativeMsisdns" : [ ],
  "details" : { },
  "externalServices" : {
    "recordId" : 38,
    "pipedrivePersonId" : null,
    "pipedriveDealId" : null,
    "shopifyCustomerId" : null,
    "shoperClientId" : null,
    "shoperOrderClientId" : null,
    "hubspotContactId" : null,
    "zendeskEndUserId" : null
  }
}
Response results
Path Type Description
id Number id of contact
alternativeMsisdns Array Msisdns of contact
createdAt String Creation date of contact
firstName String Updated first name of contact
lastName String Updated last Name of contact
company String Updated company of contact
externalLink String Updated external link related to the contact
email String Updated email of contact
lastModificationDate String date of last modification
externalServices Object External services data
externalServices.recordId Number id of contact


Possible errors
Error key Description
RESOURCE_NOT_FOUND When contact doesn’t exist

Delete contact

Deletes contact with given id. Keep in mind that contact state may prevent it from deletion, e.g. when it is in the calling state.

Example request:

DELETE /api/v1/contacts/39 HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

/api/v1/contacts/{contactId}

Parameter Description
contactId Contacts’s id to delete
Example response:

HTTP/1.1 200 OK


Possible errors
Error key Description
RESOURCE_NOT_FOUND When contact doesn’t exist
CANNOT_DELETE_CONTACT When it is forbidden to delete given contact, e.g. it is in call state

Get contact details

Returns detailed information about contact. Contact details are irregular structure so they are represented as JSON.

Example request:

GET /api/v1/contacts/52/details HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 42

{
  "gender": "male",
  "country": "USA"
}


When your contact have detailed information like gender and country then the json will look like this :
{ "gender":"male", "country":"USA" }

/api/v1/contacts/{contactId}/details

Parameter Description
contactId Contacts’s id to get


Possible errors
Error key Description
RESOURCE_NOT_FOUND When contact doesn’t exist

Add and update contact details

Example request:

POST /api/v1/contacts/25/details HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app
Content-Length: 42

{
  "surname" : "doe",
  "name" : "john"
}
Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 82

{
  "gender": "male",
  "country": "USA",
  "surname" : "doe",
  "name" : "john"
}

Method updates additional information in contact. JSON with key and value should be provided in post body to update values. If keys provided in JSON body existed before, they are updated with new values. If they didn’t exist, they are added to the existing document.

/api/v1/contacts/{contactId}/details

Parameter Description
contactId Contacts’s id which details will be edited


Possible errors
Error key Description
RESOURCE_NOT_FOUND When contact doesn’t exist

Edit contact details

Example request:

PUT /api/v1/contacts/41/details HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app
Content-Length: 42

{
  "surname" : "doe",
  "name" : "john"
}

Methods edits information in contact detail. JSON with key and value, which exist in details should be send in post body to edit. If provided elements do not appear in existing element, system won’t include them.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 82

{
  "gender": "male",
  "country": "USA",
  "surname" : "doe",
  "name" : "john"
}

/api/v1/contacts/{contactId}/details

Parameter Description
contactId Contacts’s id which details will be updated


Possible errors
Error key Description
RESOURCE_NOT_FOUND When contact doesn’t exist

Import contact

Allows to import new contact by object with your structure definition.

Example request:

POST /api/v1/contacts HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app
Content-Length: 883

{
  "forceNewEntity" : false,
  "existingContactId" : null,
  "firstNameColumnName" : "firstNameColumnName",
  "lastNameColumnName" : "lastNameColumnName",
  "emailColumnName" : "emailColumnName",
  "companyColumnName" : "companyColumnName",
  "externalLinkColumnName" : null,
  "externalOrderLinkColumnName" : null,
  "tagsColumnNames" : null,
  "alternativeMsisdnColumnNames" : [ "mainMsisdnColumnName" ],
  "externalServicesColumnNames" : { },
  "detailsList" : [ ],
  "details" : {
    "mainMsisdnColumnName" : "+14153661222",
    "firstNameColumnName" : "Firstname",
    "lastNameColumnName" : "Lastname",
    "emailColumnName" : "[email protected]",
    "companyColumnName" : "Company name",
    "externalLinkColumnName" : "https://www.crazycall.com",
    "alternativeMsisdnColumnName" : "+48717221111",
    "plainColumnName" : "test",
    "tagColumnName" : "exampleTag"
  }
}
Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 818

{
  "id" : 75,
  "firstName" : "Firstname",
  "lastName" : "Lastname",
  "company" : "Company name",
  "externalLink" : null,
  "externalOrderLink" : null,
  "createdAt" : "2022-09-28T12:43:38.000+00:00",
  "lastModificationDate" : "2022-09-28T12:43:38.217+00:00",
  "source" : "API",
  "email" : "[email protected]",
  "alternativeMsisdns" : [ ],
  "details" : {
    "alternativeMsisdnColumnName" : "+48717221111",
    "externalLinkColumnName" : "https://www.crazycall.com",
    "tagColumnName" : "exampleTag",
    "plainColumnName" : "test"
  },
  "externalServices" : {
    "recordId" : 75,
    "pipedrivePersonId" : null,
    "pipedriveDealId" : null,
    "shopifyCustomerId" : null,
    "shoperClientId" : null,
    "shoperOrderClientId" : null,
    "hubspotContactId" : null,
    "zendeskEndUserId" : null
  }
}
Request fields
Path Type Description
forceNewEntity Boolean Always creates new contact
existingContactId Null Updates contact with the given id
firstNameColumnName String Name of first name column
lastNameColumnName String Name of last name column
emailColumnName String Name of email column
companyColumnName String Name of company column
externalLinkColumnName Null Name of external link column
tagsColumnNames Null Names of columns containing tags
alternativeMsisdnColumnNames Array Names of msisdn columns
details Object Data to be imported
Response results
Path Type Description
id Number ID of the contact
alternativeMsisdns Array Msisdns associated with the contact
firstName String FirstName associated with the contact
lastName String Last name associated with the contact
company String Company associated with the contact
externalLink String External link related to the contact
email String Email associated with the contact
createdAt String Date when contact was created
lastModificationDate String Contact’s last modification date
externalServices Object External services data
externalServices.recordId Number id of contact


Possible errors
Error key Description
DETAILS_EMPTY No data was passed
MAIN_MSISDN_EMPTY No main msisdn was passed
MAIN_MSISDN_NOT_EXIST Column with given main msisdn does not exist

Contact history

You can get contact history

Example request:

GET /api/v1/contacts/13/history HTTP/1.1
Content-Type: application/json;charset=utf-8
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

/api/v1/contacts/{contactId}/history

Parameter Description
contactId Contacts’s id to get
Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 518

[ {
  "id" : 16,
  "contactId" : 13,
  "createdAt" : "2022-09-28T12:43:34.232+00:00",
  "type" : "NOTE",
  "agentUsername" : "[email protected]",
  "name" : "John",
  "surname" : "Doe",
  "recordingAvailable" : false,
  "note" : "test",
  "callDetails" : { }
}, {
  "id" : 5,
  "contactId" : 13,
  "createdAt" : "2022-09-28T12:43:33.873+00:00",
  "type" : "IMPORT_CONTACT",
  "agentUsername" : "[email protected]",
  "name" : "John",
  "surname" : "Doe",
  "recordingAvailable" : false,
  "callDetails" : { }
} ]
Response results
Path Type Description
[].id Number Contact event id
[].contactId Number Contact id
[].createdAt String Date when event was created
[].type String Type describing what happened with contact
[].customStatus String Custom status set by agent
[].clientMsisdn String Client phone number
[].historicalCallerId String Number that contact was called from
[].callerIdInfo Object Additional info about caller id the contact was called from
[].callerIdInfo.msisdn String Caller id itself
[].callerIdInfo.label String Label of the caller id
[].callerIdInfo.isoCountry String ISO country code of the caller id
[].callId Number Id of call connected with event
[].callLength Number Length of call connected with event
[].agentUsername String Agent’s username (typically email)
[].name String Agent’s name
[].surname String Agent’s surname
[].newMsisdn String If number was changed it will be new number added to contact
[].oldMsisdn String If number was changed it will be old number added to contact
[].recordingAvailable Boolean Indicates if call recording is ready to download
[].note String Note added to contact
[].appType String Application used for the call. Can be either: BROWSER, WIDGET, MOBILE, ZENDESK, WEB_WIDGET, POPUP
[].callDetails Object Additional fields related to the call


Possible errors
Error key Description
RESOURCE_NOT_FOUND When contact doesn’t exist

Add note

You can add note to contact

/api/v1/contacts/{contactId}/note

Parameter Description
contactId Contacts’s id that this note was created for.
Example request:

POST /api/v1/contacts/36/note HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app
Content-Length: 21

{
  "note" : "Note"
}
Request fields
Path Type Description
note String Contents of note
Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 249

{
  "contactId" : 36,
  "alternativeMsisdns" : [ "+14153661222" ],
  "status" : "OPEN",
  "lock" : "NO_LOCK",
  "lastModificationDate" : "2022-09-28T12:43:35.533Z",
  "createdAt" : "2022-09-28T12:43:35.533Z",
  "createdBy" : 23,
  "origin" : "API"
}
Response results
Path Type Description
contactId Number Id of the contact
alternativeMsisdns Array Msisdns of the contact
status String Contact’s status
lock String Lock type, possible locks: NO_LOCK, IN_QUEUE_APP, CALLING, UPDATE_LOCK
lastModificationDate String Last modification date
createdAt String Contact’s creation date
createdBy Number Id of User who created the contact
origin String Contact’s origin


Possible errors
Error key Description
NOTE_EMPTY No note was passed
USER_NOT_EXIST User with given email does not exist

Get all alternative msisdns of specific contact

Contact can be associated with more than one number, i.e. office, home, mobile. All numbers except primary one are called alternative msisdns. Agent, when calling, can manage and call alternative msisdn.

Example request:

GET /api/v1/contacts/24/alternative-msisdns HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 93

[ {
  "id" : 16,
  "msisdn" : "+14153661222"
}, {
  "id" : 17,
  "msisdn" : "+6499519999"
} ]

/api/v1/contacts/{contactId}/alternative-msisdns

Parameter Description
contactId Contacts’s id to get
Response results
Path Type Description
[].id Number Alternative msisdn ID attached to newly created msisdn entity
[].msisdn String Msisdn that you added


Possible errors
Error key Description
RESOURCE_NOT_FOUND When contact doesn’t exist

Add new alternative msisdn

This API allows you to attach new alternative msisdns to contact.

Example request:

POST /api/v1/contacts/12/alternative-msisdns HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app
Content-Length: 30

{
  "msisdn" : "+6499519999"
}
Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 42

{
  "id" : 4,
  "msisdn" : "+6499519999"
}

/api/v1/contacts/{contactId}/alternative-msisdns

Parameter Description
contactId Contacts’s id to append alternative msisdn
Request fields
Path Type Description
msisdn String Phone number that will be attached to contact
Response results
Path Type Description
id Number Alternative msisdn ID attached to newly created msisdn entity
msisdn String Msisdn that you added


Possible errors
Error key Description
MSISDN_EXISTS Your msisdn already exists
INVALID_MSISDN You typed invalid msisdn
RESOURCE_NOT_FOUND Cannot find contact with given id

Delete alternative msisdn

This API allows you to remove msisdns from contact.

Example request:

DELETE /api/v1/contacts/63/alternative-msisdns/57 HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 43

{
  "id" : 57,
  "msisdn" : "+6499519999"
}

/api/v1/contacts/{contactId}/alternative-msisdns/{msisdnId}

Parameter Description
contactId Contacts’s id that alternative msisdn belongs to
msisdnId Alternative msisdn ID to be removed
Response results
Path Type Description
id Number Alternative msisdn ID that were removed
msisdn String Msisdn associated with deleted alternative msisdn entity


Possible errors
Error key Description
PRIMARY_MSISDN You cannot delete alternative msisdn that is primary at the same time
RESOURCE_NOT_FOUND Cannot find alternative msisdn with given id

Phone numbers

Phone number (msisdn) is basic object for calling purposes.

Get all msisdns

Returns available msisdns to given client

Example request:

GET /api/v1/msisdns HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 322

[ {
  "id" : 21,
  "msisdn" : "+48717221111",
  "eea" : true,
  "isoCountry" : "pl",
  "label" : "dezBh",
  "initial" : false,
  "availableForSms" : false
}, {
  "id" : 22,
  "msisdn" : "+14153661222",
  "eea" : false,
  "isoCountry" : "us",
  "label" : "+14153661222",
  "initial" : false,
  "availableForSms" : false
} ]
Response results
Path Type Description
[].id Number Msisdn’s id
[].msisdn String Actual phone number
[].label String Msisdn’s label to be displayed
[].eea Boolean Is number in European Economic Area
[].isoCountry String Number’s iso country code

Set up call forwarding for incoming calls

You can set up call forwarding to automatically transfer all incoming calls from your Channels App number to any other number you specify, i.e. your cellphone.

Example request:

POST /api/v1/inbound/configuration/numbers/20/forward HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app
Content-Length: 36

{
  "phoneNumber" : "+14153661222"
}

/api/v1/inbound/configuration/numbers/{msisdnId}/forward

Parameter Description
msisdnId Phone number’s id which configuration will be updated
Example response body:


{
  "status" : "success",
  "data" : null
}
Request fields
Path Type Description
phoneNumber String (required) Phone number where calls will be forwarded


Possible errors
Error key Description
PHONE_NUMBER_INVALID When passed phone number in invalid format
MSISDN_NOT_FOUND When there is no phone number with given id
CANNOT_CONFIGURE_CLIENTS_MSISDN When trying to configure client’s phone number

Do Not Call List

Do Not Call List is a list of phone numbers (msisdns) you do not wish to call. Numbers from that list will not be dialed, even when imported as contacts. You can block and unblock numbers from that list.

Get Do Not Call List history

Returns history of phone numbers (msisdns) which have been on the list.

Example request:

GET /api/v1/dnclist?page=1&limit=5&dateFrom=2013-05-03T20%3A30%3A40&dateTo=2119-05-03T20%3A30%3A40&msisdnLike=64&orderColumn=eventDate&direction=DESC HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Request parameters
Parameter Description
page Page number to be returned.
limit Returned page will consist of that many elements.
dateFrom Filter result to only records newer or equal to given date. (e.g. 2013-05-03T20:30:40.100Z)
dateTo Filter result to only records older or equal to given date. (e.g. 2013-05-03T20:30:40.100Z)
msisdnLike Phone number pattern, e.g. “123” matches all numbers containing sequence “123”
orderColumn Order column. Available: msisdn, username, eventDate, status.
direction Sorting direction. Available: ASC, DESC
Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 439

{
  "total" : 2,
  "data" : [ {
    "msisdn" : "+16475586333",
    "eventDate" : "2022-09-28T12:43:41.079Z",
    "userId" : 52,
    "status" : "UNBLOCKED",
    "username" : "[email protected]",
    "sameMsisdnEventsCount" : 2
  }, {
    "msisdn" : "+6499519999",
    "eventDate" : "2022-09-28T12:43:41.053Z",
    "userId" : 52,
    "status" : "UNBLOCKED",
    "username" : "[email protected]",
    "sameMsisdnEventsCount" : 4
  } ]
}
Response results
Path Type Description
total Number Total elements count returned by the query
data Array Array of events
data.[].msisdn String Event phone number
data.[].eventDate String Event date
data.[].userId Number User Id of user who made event
data.[].status String Blacklist record event status
data.[].username String Username of user who made event
data.[].sameMsisdnEventsCount Number Same phone numbers events count


Possible errors
Error key Description
EMPTY_FIELD When page or limit is not present
PAGE_NUMBER_INVALID When page parameter was invalid
LIMIT_INVALID When limit parameter was invalid
WRONG_ORDER_COLUMN When order column is does not match any of msisdn, username, eventDate, status.


Blacklist record status

Status Description
BLOCKED Number has been banned
UNBLOCKED Number has been unlocked

Get number Do Not Call List history

Returns history of a particular number from Do Not Call List

Example request:

GET /api/v1/dnclist/+6499519999 HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 316

[ {
  "msisdn" : "+6499519999",
  "eventDate" : "2022-09-28T12:43:41.242Z",
  "userId" : 53,
  "status" : "UNBLOCKED",
  "username" : "[email protected]"
}, {
  "msisdn" : "+6499519999",
  "eventDate" : "2022-09-28T12:43:41.223Z",
  "userId" : 53,
  "status" : "BLOCKED",
  "username" : "[email protected]"
} ]
Response results
Path Type Description
[] Array Array of contacts
[].msisdn String Blacklisted phone number
[].eventDate String Date of event
[].userId Number User Id of user who made event
[].status String Blacklist record event status
[].username String Username of user who made event


Possible errors
Error key Description
MSISDN_NOT_FOUND When phone number is not present in the Do Not Call List.


Blacklist record status

Status Description
BLOCKED Number has been banned
UNBLOCKED Number has been unlocked

Block msisdn

You can block phone numbers (msisdn) to the Do Not Call List. Incorrect numbers will be ignored.

Example request:

POST /api/v1/dnclist/block HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app
Content-Length: 33

[ "+6499519999", "+16475586333" ]
Request fields
Path Type Description
[] Array Array of msisdns to block
Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 237

[ {
  "msisdn" : "+16475586333",
  "eventDate" : "2022-09-28T12:43:40.772Z",
  "userId" : 50,
  "status" : "BLOCKED"
}, {
  "msisdn" : "+6499519999",
  "eventDate" : "2022-09-28T12:43:40.772Z",
  "userId" : 50,
  "status" : "BLOCKED"
} ]
Response results
Path Type Description
[] Array Array of created events
[].msisdn String Event’s phone number
[].eventDate String Date of event
[].userId Number User Id of user who made event
[].status String Blacklist record event status


Blacklist record status

Status Description
BLOCKED Number has been banned
UNBLOCKED Number has been unlocked

Unblock msisdn

You can unblock phone numbers (msisdn) from the Do Not Call List. Incorrect numbers will be ignored.

Example request:

POST /api/v1/dnclist/unblock HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app
Content-Length: 33

[ "+6499519999", "+16475586333" ]
Request fields
Path Type Description
[] Array Array of msisdns to unblock
Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 241

[ {
  "msisdn" : "+6499519999",
  "eventDate" : "2022-09-28T12:43:40.906Z",
  "userId" : 51,
  "status" : "UNBLOCKED"
}, {
  "msisdn" : "+16475586333",
  "eventDate" : "2022-09-28T12:43:40.906Z",
  "userId" : 51,
  "status" : "UNBLOCKED"
} ]
Response results
Path Type Description
[] Array Array of created events
[].msisdn String Event’s phone number
[].eventDate String Date of event
[].userId Number User Id of user who made event
[].status String Blacklist record event status


Blacklist record status

Status Description
BLOCKED Number has been banned
UNBLOCKED Number has been unlocked

Calls

Call is a domain representation of call done by agent. It has properties describing e.g. length of calling, and agent identification.

Get all calls

You can retrieve all calls made on your account.

Request parameters
Parameter Description
limit (required) Limit number of calls
page (required) Page number
msisdns Array of phone numbers associated with contact
Example request:

GET /api/v1/calls?limit=1&page=1 HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 677

[ {
  "id" : 8500253788301174784,
  "startDate" : "2022-09-27T12:43:32.772Z",
  "finishDate" : "2022-09-27T12:43:32.772Z",
  "answeredDate" : "2022-09-27T12:43:32.772Z",
  "lengthSeconds" : 0,
  "direction" : "OUTBOUND",
  "msisdn" : "",
  "agentUsername" : "[email protected]",
  "agentName" : "John",
  "agentSurname" : "Doe",
  "agentMsisdn" : null,
  "agentMsisdnIsoCountry" : null,
  "agentMsisdnLabel" : null,
  "contactName" : null,
  "contactSurname" : null,
  "appType" : "BROWSER",
  "recordId" : 11,
  "recordEventType" : null,
  "contacts" : [ ],
  "callDetails" : {
    "key" : "value",
    "number" : 7
  },
  "recordingExists" : false,
  "answered" : true
} ]

Data will be sorted by finished date.

Response results
Path Type Description
[] Array All finished calls
[].id Number Call’s id
[].recordingExists Boolean Indicates whether call has a recording.
[].startDate String Date and time when call has been started
[].finishDate String Date and time when call has been finished
[].answeredDate String Date and time when call has been answered
[].lengthSeconds Number Duration of the call in seconds
[].direction String Direction of the call
[].msisdn String Actual phone number
[].agentUsername String Calling agent’s username (typically email)
[].agentName String Calling agent’s name
[].agentSurname String Calling agent’s surname
[].answered Boolean Indicates whether call has been answered
[].agentMsisdn String Agent phone number
[].agentMsisdnIsoCountry String Agent phone number country code
[].agentMsisdnLabel String Agent phone number label
[].contactName String Contact’s name
[].contactSurname String Contact’s surname
[].appType String Application used for the call. Can be either: BROWSER, WIDGET, MOBILE, ZENDESK, WEB_WIDGET, POPUP
[].callDetails Object Additional fields related to the call


Possible directions

Direction Description
INBOUND Call inbound (to CrazyCall app)
OUTBOUND Call outbound (from CrazyCall app)

Get specific call

You can receive specific call established with your account.

/api/v1/calls/{id}

Parameter Description
id Call’s id to get
Example request:

GET /api/v1/calls/6891261048562846720 HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 673

{
  "id" : 6891261048562846720,
  "startDate" : "2022-09-27T12:43:32.499Z",
  "finishDate" : "2022-09-27T12:43:32.499Z",
  "answeredDate" : "2022-09-27T12:43:32.499Z",
  "lengthSeconds" : 0,
  "direction" : "OUTBOUND",
  "msisdn" : "",
  "agentUsername" : "[email protected]",
  "agentName" : "John",
  "agentSurname" : "Doe",
  "agentMsisdn" : null,
  "agentMsisdnIsoCountry" : null,
  "agentMsisdnLabel" : null,
  "contactName" : null,
  "contactSurname" : null,
  "appType" : "BROWSER",
  "recordId" : 10,
  "recordEventType" : null,
  "contacts" : [ ],
  "callDetails" : {
    "key" : "value",
    "number" : 7
  },
  "recordingExists" : false,
  "answered" : true
}
Response results
Path Type Description
id Number Call’s id
recordingExists Boolean Indicates whether call has a recording.
startDate String Date and time when call has been started
finishDate String Date and time when call has been finished
answeredDate String Date and time when call has been answered
lengthSeconds Number Length of the call in seconds
direction String Direction of the call
msisdn String Actual phone number
agentUsername String Agent’s username (typically email)
agentName String Agent’s name
agentSurname String Agent’s surname
answered Boolean Logic value describing if call was answered
agentMsisdn String Agent phone number
agentMsisdnIsoCountry String Agent phone number country code
agentMsisdnLabel String Agent phone number label
contactName String Contact’s name
contactSurname String Contact’s surname
appType String Application used for the call. Can be either: BROWSER, WIDGET, MOBILE, ZENDESK, WEB_WIDGET, POPUP
callDetails Object Additional fields related to the call
contacts Array Related contacts data


Possible errors
Error key Description
CALL_NOT_FOUND When the call with the given id is not available


Possible directions

Direction Description
INBOUND Call inbound (to CrazyCall app)
OUTBOUND Call outbound (from CrazyCall app)

Call recordings

Each call in Channels App is recorded and is available for download according to the plan you have purchased.

This method generates a link to the call recording. Recording availability can be limited by the plan you’ve purchased. Please be aware the link is public and doesn’t require an API key to download the file. A generated link contains a token at the end, which can be used to delete the link.

Request fields
Path Type Description
callId Number (required) Call’s id that belongs to the recording
Example request:

POST /api/v1/recordings HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app
Content-Length: 36

{
  "callId" : 5924178961866365952
}
Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 156

{
  "callId" : 5924178961866365952,
  "link" : "http://crazycall.com/recording-files/your-account-hash.crazycall.com/fda8b638-abba-4760-8a4d-50956fe63d50"
}
Response results
Path Type Description
callId Number Call’s id that belongs to the recording.
link String Link to the recording.


Possible errors
Error key Description
CALL_NOT_FOUND When there is no matching call.
RECORDING_NOT_FOUND When there is no matching recording to provided call, or it hasn’t been processed yet.
DATE_LIMIT_EXCEEDED When the provided date exceeds the limit in your plan.

Returns all generated links along with call id.

Example request:

GET /api/v1/recordings HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 160

[ {
  "callId" : 8437971817015721984,
  "link" : "http://crazycall.com/recording-files/your-account-hash.crazycall.com/78763659-faf2-4051-abf3-f57a7a44292e"
} ]
Response results
Path Type Description
[] Array Array of all generated links.
[].callId Number Call’s id that belongs to the recording.
[].link String Link to the recording.

This method deletes a link to the public recording. This method does not remove recording itself.

/api/v1/recordings/{token}

Parameter Description
token (required) Token provided with the link.
Example request:

DELETE /api/v1/recordings/d39419ce-7d23-48c3-8e35-18e5999235c2 HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK


Possible errors
Error key Description
RECORDING_NOT_FOUND When there is no matching recordings to provided token.

This method generates a link to the archive containing call recordings matching provided parameters. Parameters may be limited by the plan you’ve purchased. Please be aware the link is public and doesn’t require an API key to download the file. A generated link contains a token at the end, which can be used to delete the link.

Request fields
Path Type Description
dateFrom String (required) Filter result to call recordings newer or equal to a given date (e.g. 2019-01-01T20:30:40.100Z).
dateTo String (required) Filter result to call recordings older or equal to a given date (e.g. 2019-01-01T20:30:40.100Z).
msisdns Array Phone numbers you have been calling to and want to get recordings from.
userIds Array Ids of users who were participating in the call.
Example request:

POST /api/v1/archive HTTP/1.1
Content-Type: application/json
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app
Content-Length: 146

{
  "msisdns" : [ ],
  "userIds" : [ ],
  "projectIds" : [ ],
  "dateFrom" : "2022-09-26T12:43:18.000Z",
  "dateTo" : "2022-09-28T12:43:18.000Z"
}
Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 209

{
  "link" : "http://crazycall.com/recording-archives/your-account-hash.crazycall.com/61655770-2a38-481c-a20c-dc7ebc13a458",
  "dateFrom" : "2022-09-26T12:43:18.000Z",
  "dateTo" : "2022-09-28T12:43:18.000Z"
}
Response results
Path Type Description
link String Link to the created archive.
dateFrom String Lower bound of date range which covers archive.
dateTo String Upper bound of date range which covers archive.


Possible errors
Error key Description
RECORDING_NOT_FOUND When there are no matching recordings to provided parameters.
DATE_LIMIT_EXCEEDED When the provided date exceeds the limit in your plan.

Returns all generated links along with date ranges they cover.

Example request:

GET /api/v1/archive HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 213

[ {
  "link" : "http://crazycall.com/recording-archives/your-account-hash.crazycall.com/715b550d-e8c9-4f7f-9120-200dec82b05f",
  "dateFrom" : "2022-09-26T12:43:17.000Z",
  "dateTo" : "2022-09-28T12:43:17.000Z"
} ]
Response results
Path Type Description
[] Array Array of all generated links along with date ranges they cover.
[].link String Link to the created archive.
[].dateFrom String Lower bound of date range which covers archive.
[].dateTo String Upper bound of date range which covers archive.

This method deletes a link to the already created archive.

/api/v1/archive/{token}

Parameter Description
token (required) Token provided with the link.
Example request:

DELETE /api/v1/archive/6b3dca2a-8588-47aa-84bf-b8e6d3de87cc HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK


Possible errors
Error key Description
RECORDING_NOT_FOUND When there are no matching recordings to provided parameters.
ARCHIVE_NOT_CREATED_YET When the archive link has been created, but the archive itself has not been created yet.

Get recording that belongs to the call

You can retrieve a call’s recording which is an audio file. Each call between agent and customer is recorded, and is available for download according to the plan you have purchased. The file is streamed.

/api/v1/call/{callId}/recording

Parameter Description
callId (Required) Call’s id that belongs to the recording
Example request:

GET /api/v1/call/7592791440282102784/recording HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Length: 53
Content-Type: application/octet-stream

The content will be a byte stream from an audio file.


Possible errors
Error key Description
CALL_NOT_FOUND When the call with the given id is not available
RECORDING_NOT_FOUND When recording is not available for the given call id.

Finance

Finance represents your current plan’s settings and monetary balance

Get balance

Example request:

GET /api/v1/finance/balance?dateFrom=2022-09-28T12%3A43%3A31.000Z HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 86

{
  "balance" : {
    "monetary" : 10,
    "voice" : 0
  },
  "secondsUsedToday" : 0
}

You can receive your current balance. It depends on your plan.

Request parameters
Parameter Description
dateFrom (required) Date in ISO date format (e.g. 2022-09-28T12:43:31.000Z)
Response results
Path Type Description
balance Object Represents current balance
balance.monetary Number Current balance (in plan’s currency)
balance.voice Number Free call time from plan (in seconds)
secondsUsedToday Number How many free seconds was used in day given as parameter (+24h)


Possible errors
Error key Description
PARAMETER.NOT_PRESENT When dateFrom was not present
DATE_INVALID Date was passed in invalid format

Get destinations

Example request:

GET /api/v1/finance/plans/destinations HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 8254

{
  "destinations" : {
    "GB_Mobile" : {
      "countryIsoCode" : "gb",
      "description" : "Mobile"
    },
    "US_Local" : {
      "countryIsoCode" : "us",
      "description" : "Local"
    },
    "RO_Mobile" : {
      "countryIsoCode" : "ro",
      "description" : "Mobile"
    },
    "MX_All" : {
      "countryIsoCode" : "mx",
      "description" : "All"
    },
    "AT_Local" : {
      "countryIsoCode" : "at",
      "description" : "Local"
    },
    "BD_All" : {
      "countryIsoCode" : "bd",
      "description" : "All"
    },

    ...

  },
  "destinationGroups" : {
    "basic" : [ "SK_Local", "ZA_Local", "KR_Local", "SE_Mobile", "GB_Mobile", "IS_Local", "IE_Local", "IL_Local",  ...],
    "free" : [ "BR_Local", "CA_Local", "CN_All", "DK_Local", "FR_Local", "DE_Local",  ... ],
    "regular" : [ "BR_Local", "CA_Local", "PT_Mobile", "RE_Local", "RO_Mobile", "SM_Local", "SG_All", "VE_Local",  ...]
  }
}

Get a list of countries eligible to be called for free, subject to your plans’ voice/minutes limit.

Response results
Path Type Description
destinations Object All available destinations
destinations.*.countryIsoCode String ico code for specific type
destinations.*.description String Short description
unlimitedVoiceBalance Object Countries with unlimited calls within given plan
unlimitedVoiceBalance.regular Array Countries with unlimited calls in regular plan
unlimitedVoiceBalance.call_forwarding Array Countries with unlimited calls in call forwarding plan
destinationGroups Object Available countries per plan
destinationGroups.free Array Countries in free plan
destinationGroups.basic Array Countries in basic plan
destinationGroups.regular Array Countries in regular plan
destinationGroups.call_forwarding Array Countries in call forwarding plan

Subscription

Example request:

GET /api/v1/finance/subscription HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 481

{
  "type" : "CHANNELS",
  "status" : "ACTIVE",
  "plan" : "plan_CHANNELS_USD_MONTHS_TCDjlgp",
  "quantity" : 10,
  "voiceBalanceSeconds" : 30000,
  "discountPercentage" : 10,
  "discountType" : "FOREVER",
  "discountValid" : true,
  "periodStart" : 1663505011,
  "periodEnd" : 1666097011,
  "destinationCountriesCount" : 90,
  "cancelAtPeriodEnd" : false,
  "planCurrency" : "USD",
  "planPrice" : 0.95,
  "discountDollars" : 10.0,
  "trial" : false,
  "subscriptionPrice" : 9.5
}

Receive your current subscription. Remember - when you try to upgrade plan it will be available after old subscription expired.

Response results
Path Type Description
plan String Plan’s name
status class com.crazycall.subscription.model.SubscriptionStatus Subscription status
planPrice Number Basic price for this plan (per user)
planCurrency String Currency of the plan in ISO 4217 format
quantity Number Amount of money available now
voiceBalanceSeconds Number Time (in seconds) of free calls
discountPercentage Number Available discount’s percentage
discountType class com.crazycall.subscription.model.DiscountType One of FOREVER, ONCE, and REPEATING
discountValid Boolean Applied coupon is still valid
discountDollars Number Available amount of discount
periodStart Number Date (in millis) when subscription started
periodEnd Number Date (in millis) when subscription will end
destinationCountriesCount Number Number of countries for voice balance
trial Boolean Is this subscription a trial
subscriptionPrice Number Total price of this subscription
cancelAtPeriodEnd Boolean Is the subscription scheduled for cancellation

Reports

Download the reports for your calls and effectiveness.

Example request:

GET /api/v1/reports?dateFrom=2022-09-23&dateUntil=2022-09-28&timezoneOffsetMinutes=-120&reportTypes=DAILY_CONTACT_STATUS&reportTypes=BILLINGS&reportTypes=LAST_CONTACT_EVENTS_DUMP HTTP/1.1
x-api-token: your-secret-api-key
Account: your-account-hash
Host: api.channels.app

Request parameters
Parameter Description
dateFrom (required) The date from which reports will be generated (e.g. 2017-12-12)
dateUntil (required) The finish date of generated reports (e.g. 2017-12-12)
timezoneOffsetMinutes Time offset from UTC (in minutes, can be negative, default 0)
reportTypes (required) Type of reports to generate (see the descriptions below)
Example response:

HTTP/1.1 200 OK
Content-Type: application/zip;charset=UTF-8
Reports-Total: 4
Reports-Success: 2
Reports-Empty: 2
Reports-Empty-Name: SCRIPT_ANSWERS
Reports-Empty-Name: BILLINGS
Content-Disposition: attachment; filename="reports_2017-10-26.zip"
Content-Length: 6806

the content will be a file with reports (application/x-ms-excel if only one file is generated, application/zip otherwise)


reportTypes parameter is an array. We will accept both reportTypes=TYPE1&reportType=TYPE2 and reportTypes=TYPE1,TYPE2 formats.

As a response, you will receive a file with reporting data. If only one report is selected, the file will be in .xlsx format. Otherwise, the compressed .zip file will be downloaded with all selected reports as .xlsx.
If we cannot generate any report (due to lack of data - for example, no calls were made in the selected date range) there will be an empty response with 0 as value for Reports-Success header.

The response contains Content-Disposition header with the report’s filename. It will match this pattern: {REPORT_NAME}_{CURRENT_DATE}.xlsx, (e.g. Effectiveness report_2017-10-26.xlsx) for one report and reports_{CURRENT_DATE}.zip for .zip file with {REPORT_NAME}.xlsx reports.


Additional headers

Header Description
Reports-Total Number of all downloaded reports
Reports-Empty Number of empty reports (we were unable to generate it due to the lack of data)
Reports-Success Number of downloaded reports with data
Reports-Empty-Name Types of empty reports


Possible errors
Error key Description
DATE_EMPTY Cannot find dateFrom or dateUntil in your request
REPORT_TYPES_EMPTY Cannot find any report type
PARAM_UNEXPECTED Cannot generate overall report with given parameters
REPORT_NOT_IN_BACKWARD_DAYS_RANGE Your plan doesn’t allow to get reports from given date
REPORT_WRONG_ENTERED_DATES Invalid range - dateFrom is after dateUntil
HOURS_OUT_OF_RANGE timezoneOffsetMinutes value is above 1439 (one day in minutes)

Billings

Report Type: BILLINGS

With this report, you can see how much time each call takes and costs. It is counted from the moment your contact answers the call until the moment he or she hangs up. The time waiting for the answer and the time after the call is excluded.

Webhooks

Webhooks allow you to configure a URL that will be notified every time an event occurs on your account. When one of the events you subscribe to happens, Channels App will send a json object representing that event through a HTTP POST request to your webhooks URL.
Please keep in mind that webhook receiver should respond within reasonable time with any HTTP status. Otherwise, if such situation occurs frequently, webhook will be disabled, and instance owner will be notified via email.
Also, inability to connect with defined endpoint will result in disabling the webhook.

Webhook configuration

To find webhook settings, click on your Account icon in the top right corner, then select For Developers. There, you can find “Webhooks” section. You can either edit your existing webhook configurations, disable them, or click “Add Webhook” at the top of the page to add a new configuration.


There are four sections that you have to fill:

  1. Event types - select at least one of the event types you want to subscribe to. They are described in more detail below. You can choose any number of types.
  2. Webhook name - select a unique name you will identify your webhook by, like “Stats app notification”
  3. URL - provide an address that events should be sent to.

Responding to webhook

We do expect to get a response from your endpoint. If there will be 10 failed webhooks in a row in an hour, the webhook will be deactivated. A failed webhook is a webhook where we couldn’t connect to the server in 1 second or the server didn’t respond in 4 seconds.

Event types

This is a list of all the types of events we currently send. We may add more at any time, so you shouldn’t rely on only these types existing in your code.

Here’s a list of dictionaries common to most event types described below.

Contact statuses

status Description
AUTOSCHEDULED Autoscheduled
CLOSED Closed
NOT_VERIFIED Not verified
OPEN Open
SCHEDULED Scheduled


Contact sources

source Description
API Api
WEBHOOK Webhook
INCOMING Incoming call
WIDGET Widget
LEAD Lead generation

  Call started

Sent when a call is being started by the agent (inbound or outbound).

Example response body:


{
  "webhookType" : "CALL_STARTED",
  "id" : 6491392581518465147,
  "contact" : {
    "id" : 6272019517636925016,
    "firstName" : "VObJzB",
    "lastName" : "tpZVgH",
    "company" : "naDMwt",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:40.024+00:00",
    "lastModificationDate" : "2022-09-28T12:43:40.024+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "opqeyx"
    },
    "externalServices" : null
  },
  "msisdn" : "+48717221111",
  "agentMsisdn" : "+14153661222",
  "agentMsisdnId" : 807888914402212224,
  "startDate" : "2022-09-28T12:36:40.024+00:00",
  "answeredDate" : "2022-09-28T12:38:40.024+00:00",
  "length" : 180,
  "agentId" : 649950076094596435,
  "agentName" : "Name",
  "agentSurname" : "Surname",
  "agentUsername" : "[email protected]",
  "recordingLink" : null,
  "direction" : "OUTBOUND",
  "lastEventType" : "REFUSE",
  "appType" : "WIDGET",
  "callDetails" : {
    "key" : "value",
    "numeric" : 7
  }
}
Response results
Path Type Description
webhookType String Type of this webhook
id Number Call Id
direction String Direction of the call. Can be either INBOUND or OUTBOUND
agentUsername String Username (typically email) of the user who created an event
agentId Number User ID of the agent who participated in the call
agentName String Name of the agent who participated in the call
agentSurname String Surname of the agent who participated in the call
agentMsisdnId Number ID of the phone number that agent was identified by during the call
agentMsisdn String Phone number that agent was identified by during the call
msisdn String Phone number of the client
recordingLink Null URL link to the recording file (in this scenario always null)
startDate String Date when the call was initialized by either party
answeredDate String Date when the call was answered (either by the client for direction OUTBOUND or by an agent for INBOUND)
length Number Length of the call in seconds
appType String Application used by the agent to handle the call. Can be either BROWSER, WIDGET or MOBILE
contact Object Contact related to the call (optional)
lastEventType String Last event set by an agent or the system (optional)
callDetails Object Additional details related to the call
contact.id Number Contact id
contact.createdAt String Contact’s import date
contact.source String Import source
contact.msisdns Array List of alternative phone numbers assigned to contact
contact.firstName String Contact’s firstname
contact.lastName String Contact’s lastname
contact.company String Contact’s company name
contact.email String Contact’s email
contact.externalLink String External link related to the contact
contact.details Object Details of the contact
contact.details.detail String Custom contact detail (optional)
contact.lastModificationDate String Date of the most recent modification
contact.externalServices Null

  Call finished

Sent always when a call is finished, regardless of its result. If the call was answered, this webhook will contain a URL link to the recording file. This means that calls that are handled by this webhook automatically have public recording links. Please see Call Recordings section for more details.

Example response body:


{
  "webhookType" : "CALL_FINISHED",
  "id" : 726018843062043702,
  "contact" : {
    "id" : 1429683832820528650,
    "firstName" : "TTTfpM",
    "lastName" : "HTwCyg",
    "company" : "woFVry",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:40.118+00:00",
    "lastModificationDate" : "2022-09-28T12:43:40.118+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "qowBxc"
    },
    "externalServices" : null
  },
  "msisdn" : "+48717221111",
  "agentMsisdn" : "+14153661222",
  "agentMsisdnId" : 1365134699516789582,
  "startDate" : "2022-09-28T12:36:40.118+00:00",
  "answeredDate" : "2022-09-28T12:38:40.118+00:00",
  "finishDate" : "2022-09-28T12:41:40.118+00:00",
  "length" : 180,
  "finishType" : "FINISHED_BY_AGENT",
  "agentId" : 8266598547883677455,
  "agentName" : "Name",
  "agentSurname" : "Surname",
  "agentUsername" : "[email protected]",
  "recordingLink" : "http://my.channels.app/recording123",
  "direction" : "OUTBOUND",
  "lastEventType" : "REFUSE",
  "appType" : "WIDGET",
  "callDetails" : {
    "key" : "value",
    "numeric" : 7
  }
}
Response results
Path Type Description
webhookType String Type of this webhook
id Number Call Id
direction String Direction of the call. Can be either INBOUND or OUTBOUND
agentUsername String Username (typically email) of the user who created an event
agentId Number User ID of the agent who participated in the call
agentName String Name of the agent who participated in the call
agentSurname String Surname of the agent who participated in the call
agentMsisdnId Number ID of the phone number that agent was identified by during the call
agentMsisdn String Phone number that agent was identified by during the call
msisdn String Phone number of the client
recordingLink String URL link to the recording file
startDate String Date when the call was initialized by either party
answeredDate String Date when the call was answered (either by the client for direction OUTBOUND or by an agent for INBOUND)
finishDate String Date when the call was finished (e.h. either party hung up)
length Number Length of the call in seconds
appType String Application used by the agent to handle the call. Can be either BROWSER, WIDGET or MOBILE
finishType String Reason why the call was finished
contact Object Contact related to the call (optional)
lastEventType String Last event set by an agent or the system after the call has ended (optional)
callDetails Object Additional details related to the call
contact.id Number Contact id
contact.createdAt String Contact’s import date
contact.source String Import source
contact.msisdns Array List of alternative phone numbers assigned to contact
contact.firstName String Contact’s firstname
contact.lastName String Contact’s lastname
contact.company String Contact’s company name
contact.email String Contact’s email
contact.externalLink String External link related to the contact
contact.details Object Details of the contact
contact.details.detail String Custom contact detail (optional)
contact.lastModificationDate String Date of the most recent modification
contact.externalServices Null


Finish type

Finish type Description
BUSY Busy
NOT_ANSWERED Not answered
FAILED Call failed
INCOMING_CALL_FAILED Incoming call was not handled
INCOMING_CALL_VOICEMAIL No agents handled the call. Voicemail prompt was played.
MAX_CALL_DURATION_EXCEEDED Call was too long
VOICE_MAIL_DROP Agent played voicemail drop message
FINISHED_BY_AGENT Agent hungup
FINISHED_BY_CLIENT Client hung up
FAILED_CONNECT_AGENT Failed to connect to agents browser
INSUFFICIENT_FUNDS Insufficient funds on the account


Last event type

Last event type Description
REFUSE contact has been closed with a custom status created by a user. It can take any value
FAILED_CONTACT a call didn’t connect to a person. It can be due to several reasons - agent reached a voicemail, the line was busy, a call has been not answered, agent disconnected before reached a person or network error
INCOMING_CALL_ANSWERED an incoming call marked with a custom status created by a user. By default, it’s “Incoming call”
VOICE_MAIL_DROP an agent has decided to play a pre-recorded message and disconnect the call

  Config change event

Sent when you add a number to one of your contacts.

Example response body:


{
  "id" : 6891362324071590913,
  "createdAt" : "2022-09-28T12:43:40.422+00:00",
  "type" : "MSISDN_CONFIG_CHANGE",
  "agentUsername" : "[email protected]",
  "userName" : "Name",
  "userSurname" : "Surname",
  "newMsisdn" : "+14153661222",
  "redirectMsisdn" : null,
  "contacts" : [ {
    "id" : 606807313170994256,
    "firstName" : "VkKgCH",
    "lastName" : "jaoZKg",
    "company" : "YaHEVy",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:40.422+00:00",
    "lastModificationDate" : "2022-09-28T12:43:40.422+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "IIBhzg"
    },
    "externalServices" : null
  } ]
}
Response results
Path Type Description
id Number Contact event id
type String Type of event (always MSISDN_CONFIG_CHANGE)
createdAt String When event was created
agentUsername String Username (typically email) of the user who created event
userName String Name of the user who created event
userSurname String Surname of the user who created event
contacts Array All contacts related to the event
contacts[0].id Number Contact id
contacts[0].createdAt String Contact’s import date
contacts[0].source String Import source
contacts[0].msisdns Array List of alternative phone numbers assigned to contact
contacts[0].firstName String Contact’s firstname
contacts[0].lastName String Contact’s lastname
contacts[0].company String Contact’s company name
contacts[0].email String Contact’s email
contacts[0].externalLink String External link related to the contact
contacts[0].details Object Details of the contact
contacts[0].details.detail String Custom contact detail (optional)
contacts[0].lastModificationDate String Date of the most recent modification
contacts[0].externalServices Null
newMsisdn String Added msisdn

  Contact details change

Sent when you updated custom information about your contact

Example response body:


{
  "id" : 2081346446731177087,
  "createdAt" : "2022-09-28T12:43:39.373+00:00",
  "type" : "CONTACT_DETAILS_CHANGE",
  "agentUsername" : "[email protected]",
  "userName" : "Name",
  "userSurname" : "Surname",
  "redirectMsisdn" : null,
  "contacts" : [ {
    "id" : 746036672878828690,
    "firstName" : "sbPsWJ",
    "lastName" : "wtiGHR",
    "company" : "eqNGPo",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:39.373+00:00",
    "lastModificationDate" : "2022-09-28T12:43:39.373+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "DqOPDb"
    },
    "externalServices" : null
  } ]
}
Response results
Path Type Description
id Number Contact event id
type String Type of event (always CONTACT_DETAILS_CHANGE)
createdAt String When event was created
agentUsername String Username (typically email) of the user who created event
userName String Name of the user who created event
userSurname String Surname of the user who created event
contacts Array All contacts related to the event
contacts[0].id Number Contact id
contacts[0].createdAt String Contact’s import date
contacts[0].source String Import source
contacts[0].msisdns Array List of alternative phone numbers assigned to contact
contacts[0].firstName String Contact’s firstname
contacts[0].lastName String Contact’s lastname
contacts[0].company String Contact’s company name
contacts[0].email String Contact’s email
contacts[0].externalLink String External link related to the contact
contacts[0].details Object Details of the contact
contacts[0].details.detail String Custom contact detail (optional)
contacts[0].lastModificationDate String Date of the most recent modification
contacts[0].externalServices Null

  Contact deleted

Sent when you removed a contact

Example response body:


{
  "id" : 1530236203793474592,
  "createdAt" : "2022-09-28T12:43:40.570+00:00",
  "type" : "DELETE_CONTACT",
  "agentUsername" : "[email protected]",
  "userName" : "Name",
  "userSurname" : "Surname",
  "redirectMsisdn" : null,
  "contacts" : [ {
    "id" : 7529458869603422546,
    "firstName" : "HtZWNI",
    "lastName" : "VCMrVP",
    "company" : "pTRoIC",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:40.570+00:00",
    "lastModificationDate" : "2022-09-28T12:43:40.570+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "RkaRqn"
    },
    "externalServices" : null
  } ]
}
Response results
Path Type Description
id Number Contact event id
type String Type of event (always DELETE_CONTACT)
createdAt String When event was created
agentUsername String Username (typically email) of the user who created event
userName String Name of the user who created event
userSurname String Surname of the user who created event
contacts Array All contacts related to the event
contacts[0].id Number Contact id
contacts[0].createdAt String Contact’s import date
contacts[0].source String Import source
contacts[0].msisdns Array List of alternative phone numbers assigned to contact
contacts[0].firstName String Contact’s firstname
contacts[0].lastName String Contact’s lastname
contacts[0].company String Contact’s company name
contacts[0].email String Contact’s email
contacts[0].externalLink String External link related to the contact
contacts[0].details Object Details of the contact
contacts[0].details.detail String Custom contact detail (optional)
contacts[0].lastModificationDate String Date of the most recent modification
contacts[0].externalServices Null

  Failed contact

Sent when you attempted a call, but you didn’t reach your contact for whatever reason, like the contact is unavailable or decided to not pickup your call.

Example response body:


{
  "id" : 4596028600803421070,
  "createdAt" : "2022-09-28T12:43:39.858+00:00",
  "type" : "FAILED_CONTACT",
  "reason" : "VOICE_MAIL",
  "callId" : 5929598213927191536,
  "callDirection" : "OUTBOUND",
  "callDetails" : {
    "key" : "value",
    "numeric" : 7
  },
  "agentUsername" : "[email protected]",
  "userName" : "Name",
  "userSurname" : "Surname",
  "redirectMsisdn" : null,
  "contactMsisdn" : "+33980091888",
  "channelsMsisdn" : "+3225889300",
  "contacts" : [ {
    "id" : 7702098432167922835,
    "firstName" : "bLomLN",
    "lastName" : "tyYtga",
    "company" : "orqtnv",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:39.858+00:00",
    "lastModificationDate" : "2022-09-28T12:43:39.858+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "WurkHO"
    },
    "externalServices" : null
  } ]
}
Response results
Path Type Description
id Number Contact event id
type String Type of event (always FAILED_CONTACT)
createdAt String When event was created
agentUsername String Username (typically email) of the user who created event
userName String Name of the user who created event
userSurname String Surname of the user who created event
contacts Array All contacts related to the event
contacts[0].id Number Contact id
contacts[0].createdAt String Contact’s import date
contacts[0].source String Import source
contacts[0].msisdns Array List of alternative phone numbers assigned to contact
contacts[0].firstName String Contact’s firstname
contacts[0].lastName String Contact’s lastname
contacts[0].company String Contact’s company name
contacts[0].email String Contact’s email
contacts[0].externalLink String External link related to the contact
contacts[0].details Object Details of the contact
contacts[0].details.detail String Custom contact detail (optional)
contacts[0].lastModificationDate String Date of the most recent modification
contacts[0].externalServices Null
callId Number Call id for a call that was attempted but failed
callDirection String Type of call, can be: INBOUND or OUTBOUND
contactMsisdn String Contact’s phone number
channelsMsisdn String Phone number assigned to your project when the call happened
reason String Failed reason
callDetails Object Additional information related to the call


Failed reasons

Reason Description
VOICE_MAIL Voice mail
BUSY Busy
NOT_ANSWERED Not answered
UNAVAILABLE_MSISDN Unavailable msisdn
NETWORK_ERROR Network error
NO_MSISDN_TO_CALL No msisdn to call
FAILED_CONNECT_AGENT Failed connect agent
INSUFFICIENT_FUNDS Insufficient funds

  Contact import

Sent when you created new contacts, e.g. through the API call

Example response body:


{
  "id" : 7636207245697344852,
  "createdAt" : "2022-09-28T12:43:40.269+00:00",
  "type" : "IMPORT_CONTACT",
  "agentUsername" : "[email protected]",
  "userName" : "Name",
  "userSurname" : "Surname",
  "redirectMsisdn" : null,
  "contacts" : [ {
    "id" : 669623965664288959,
    "firstName" : "ulVHDq",
    "lastName" : "nQUTTL",
    "company" : "NztEkN",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:40.269+00:00",
    "lastModificationDate" : "2022-09-28T12:43:40.269+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "bCFVJe"
    },
    "externalServices" : null
  } ]
}
Response results
Path Type Description
id Number Contact event id
type String Type of event (always IMPORT_CONTACT)
createdAt String When event was created
agentUsername String Username (typically email) of the user who created event
userName String Name of the user who created event
userSurname String Surname of the user who created event
contacts Array All contacts related to the event
contacts[0].id Number Contact id
contacts[0].createdAt String Contact’s import date
contacts[0].source String Import source
contacts[0].msisdns Array List of alternative phone numbers assigned to contact
contacts[0].firstName String Contact’s firstname
contacts[0].lastName String Contact’s lastname
contacts[0].company String Contact’s company name
contacts[0].email String Contact’s email
contacts[0].externalLink String External link related to the contact
contacts[0].details Object Details of the contact
contacts[0].details.detail String Custom contact detail (optional)
contacts[0].lastModificationDate String Date of the most recent modification
contacts[0].externalServices Null

  Incoming call answered

Sent when someone called to one of your numbers, ans agent did answer it.

Example response body:


{
  "id" : 2848915079096783788,
  "createdAt" : "2022-09-28T12:43:40.639+00:00",
  "type" : "INCOMING_CALL_ANSWERED",
  "customStatus" : "Incoming call",
  "callId" : 7426691065464142450,
  "callDirection" : "INBOUND",
  "callDetails" : {
    "key" : "value",
    "numeric" : 7
  },
  "agentUsername" : "[email protected]",
  "userName" : "Name",
  "userSurname" : "Surname",
  "redirectMsisdn" : null,
  "contactMsisdn" : "+33980091888",
  "channelsMsisdn" : "+3225889300",
  "contacts" : [ {
    "id" : 797855848663325541,
    "firstName" : "Inklmw",
    "lastName" : "uzMtWc",
    "company" : "xlBFcD",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:40.639+00:00",
    "lastModificationDate" : "2022-09-28T12:43:40.639+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "HZhqwl"
    },
    "externalServices" : null
  } ]
}
Response results
Path Type Description
id Number Contact event id
type String Type of event (always INCOMING_CALL_ANSWERED)
createdAt String When event was created
agentUsername String Username (typically email) of the user who created event
userName String Name of the user who created event
userSurname String Surname of the user who created event
contacts Array All contacts related to the event
contacts[0].id Number Contact id
contacts[0].createdAt String Contact’s import date
contacts[0].source String Import source
contacts[0].msisdns Array List of alternative phone numbers assigned to contact
contacts[0].firstName String Contact’s firstname
contacts[0].lastName String Contact’s lastname
contacts[0].company String Contact’s company name
contacts[0].email String Contact’s email
contacts[0].externalLink String External link related to the contact
contacts[0].details Object Details of the contact
contacts[0].details.detail String Custom contact detail (optional)
contacts[0].lastModificationDate String Date of the most recent modification
contacts[0].externalServices Null
callId Number Call id of the call
callDirection String Type of call, always INBOUND
contactMsisdn String Contact’s phone number
channelsMsisdn String Phone number assigned to the agent the call happened
customStatus String Status assigned to this call
callDetails Object Additional information related to the call

  Incoming call redirected

Sent when someone called to one of your numbers, but inbound configuration of your number was set to redirect the call to another number.

Example response body:


{
  "id" : 2966658708797617119,
  "createdAt" : "2022-09-28T12:43:40.201+00:00",
  "type" : "INCOMING_CALL_REDIRECTED",
  "callId" : 5114601711097629389,
  "callDirection" : "INBOUND",
  "callDetails" : {
    "key" : "value",
    "numeric" : 7
  },
  "agentUsername" : "[email protected]",
  "userName" : "Name",
  "userSurname" : "Surname",
  "redirectMsisdn" : "+48717221111",
  "contactMsisdn" : "+33980091888",
  "channelsMsisdn" : "+3225889300",
  "contacts" : [ {
    "id" : 433099964763177018,
    "firstName" : "vWZfwV",
    "lastName" : "sojdUx",
    "company" : "RWPGgG",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:40.201+00:00",
    "lastModificationDate" : "2022-09-28T12:43:40.201+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "UhhycP"
    },
    "externalServices" : null
  } ]
}
Response results
Path Type Description
id Number Contact event id
type String Type of event (always INCOMING_CALL_REDIRECTED)
createdAt String When event was created
agentUsername String Username (typically email) of the user who created event
userName String Name of the user who created event
userSurname String Surname of the user who created event
contacts Array All contacts related to the event
contacts[0].id Number Contact id
contacts[0].createdAt String Contact’s import date
contacts[0].source String Import source
contacts[0].msisdns Array List of alternative phone numbers assigned to contact
contacts[0].firstName String Contact’s firstname
contacts[0].lastName String Contact’s lastname
contacts[0].company String Contact’s company name
contacts[0].email String Contact’s email
contacts[0].externalLink String External link related to the contact
contacts[0].details Object Details of the contact
contacts[0].details.detail String Custom contact detail (optional)
contacts[0].lastModificationDate String Date of the most recent modification
contacts[0].externalServices Null
callId Number Call id of the call
callDirection String Type of call, always INBOUND
contactMsisdn String Contact’s phone number
channelsMsisdn String Phone number assigned to the agent the call happened
redirectMsisdn String Number to redirect to, according to rules setup for this Channels number (optional, will not be present if the call was not redirected)
callDetails Object Additional information related to the call

  Incoming call rejected

Sent when someone attempted a call to one of your numbers, but the call was rejected. This event is also sent for failed calls, so whether you actually received the call or weren’t available

Example response body:


{
  "id" : 6425299144392669498,
  "createdAt" : "2022-09-28T12:43:39.516+00:00",
  "type" : "INCOMING_CALL_NOT_ANSWERED",
  "callId" : 7378964831733515804,
  "callDirection" : "INBOUND",
  "callDetails" : {
    "key" : "value",
    "numeric" : 7
  },
  "agentUsername" : "[email protected]",
  "userName" : "Name",
  "userSurname" : "Surname",
  "redirectMsisdn" : null,
  "contactMsisdn" : "+33980091888",
  "channelsMsisdn" : "+3225889300",
  "contacts" : [ {
    "id" : 5019019119520552768,
    "firstName" : "MQompG",
    "lastName" : "HBjHYJ",
    "company" : "MBIPeL",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:39.516+00:00",
    "lastModificationDate" : "2022-09-28T12:43:39.516+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "xzVFGw"
    },
    "externalServices" : null
  } ]
}
Response results
Path Type Description
id Number Contact event id
type String Type of event (always INCOMING_CALL_NOT_ANSWERED)
createdAt String When event was created
agentUsername String Username (typically email) of the user who created event
userName String Name of the user who created event
userSurname String Surname of the user who created event
contacts Array All contacts related to the event
contacts[0].id Number Contact id
contacts[0].createdAt String Contact’s import date
contacts[0].source String Import source
contacts[0].msisdns Array List of alternative phone numbers assigned to contact
contacts[0].firstName String Contact’s firstname
contacts[0].lastName String Contact’s lastname
contacts[0].company String Contact’s company name
contacts[0].email String Contact’s email
contacts[0].externalLink String External link related to the contact
contacts[0].details Object Details of the contact
contacts[0].details.detail String Custom contact detail (optional)
contacts[0].lastModificationDate String Date of the most recent modification
contacts[0].externalServices Null
callId Number Call id of the call
callDirection String Type of call, always INBOUND
contactMsisdn String Contact’s phone number
channelsMsisdn String Phone number assigned to the agent the call happened
callDetails Object Additional information related to the call

  Incoming call started

Sent when a call is being answered by the agent, regardless if it has been answered in Channels App or as a forwarded call.

Example response body:


{
  "webhookType" : "INBOUND_CALL_STARTED",
  "id" : 1301748205231047095,
  "contact" : {
    "id" : 1266214190395506256,
    "firstName" : "mARrAU",
    "lastName" : "SUNqOn",
    "company" : "rAALXe",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:39.766+00:00",
    "lastModificationDate" : "2022-09-28T12:43:39.766+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "mvrkDB"
    },
    "externalServices" : null
  },
  "msisdn" : "+48717221111",
  "agentMsisdn" : "+14153661222",
  "agentMsisdnId" : 3068000719635914677,
  "startDate" : "2022-09-28T12:36:39.765+00:00",
  "answeredDate" : "2022-09-28T12:37:39.765+00:00",
  "finishDate" : "2022-09-28T12:41:39.765+00:00",
  "length" : 0,
  "finishType" : "FINISHED_BY_CLIENT",
  "agentId" : 4683485421186289002,
  "agentName" : "Name",
  "agentSurname" : "Surname",
  "agentUsername" : "[email protected]",
  "recordingLink" : null,
  "direction" : "INBOUND",
  "lastEventType" : "REFUSE",
  "appType" : "BROWSER",
  "callDetails" : {
    "key" : "value",
    "numeric" : 7
  }
}
Response results
Path Type Description
webhookType String Type of this webhook
id Number Call Id
direction String Direction of the call. In this scenario it will always be INBOUND
agentUsername String Username (typically email) of the user who created an event
agentId Number User ID of the agent who participated in the call
agentName String Name of the agent who participated in the call
agentSurname String Surname of the agent who participated in the call
agentMsisdnId Number ID of the phone number that agent was identified by during the call
agentMsisdn String Phone number that agent was identified by during the call
msisdn String Phone number of the client
startDate String Date when the call was initialized by either party
answeredDate String Date when the call was answered by an agent
finishDate String Date when the call was finished (e.h. either party hung up)
length Number Length of the call in seconds
appType String Application used by the agent to handle the call. Can be either BROWSER, WIDGET or MOBILE
finishType String Reason why the call was finished
recordingLink Null URL link to the recording file (in this scenario always null)
contact Object Contact related to the call (optional)
lastEventType String Last event set by an agent or the system (optional)
callDetails Object Additional details related to the call
contact.id Number Contact id
contact.createdAt String Contact’s import date
contact.source String Import source
contact.msisdns Array List of alternative phone numbers assigned to contact
contact.firstName String Contact’s firstname
contact.lastName String Contact’s lastname
contact.company String Contact’s company name
contact.email String Contact’s email
contact.externalLink String External link related to the contact
contact.details Object Details of the contact
contact.details.detail String Custom contact detail (optional)
contact.lastModificationDate String Date of the most recent modification
contact.externalServices Null

  Note

Sent when an incoming call hasn’t been answered and a client has left a voicemail. It can only happen if it’s allowed in the phone number settings.

Example response body:


{
  "id" : 1200662141400514372,
  "createdAt" : "2022-09-28T12:43:38.949+00:00",
  "type" : "NOTE",
  "agentUsername" : "[email protected]",
  "userName" : "Name",
  "userSurname" : "Surname",
  "redirectMsisdn" : null,
  "note" : "njGxvemDYGh",
  "contacts" : [ {
    "id" : 2129168254328476845,
    "firstName" : "mkWMKU",
    "lastName" : "JBlSPY",
    "company" : "TpozWm",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:38.949+00:00",
    "lastModificationDate" : "2022-09-28T12:43:38.949+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "xWNCyQ"
    },
    "externalServices" : null
  } ]
}
Response results
Path Type Description
id Number Contact event id
type String Type of event (always NOTE)
createdAt String When event was created
agentUsername String Username (typically email) of the user who created event
userName String Name of the user who created event
userSurname String Surname of the user who created event
contacts Array All contacts related to the event
contacts[0].id Number Contact id
contacts[0].createdAt String Contact’s import date
contacts[0].source String Import source
contacts[0].msisdns Array List of alternative phone numbers assigned to contact
contacts[0].firstName String Contact’s firstname
contacts[0].lastName String Contact’s lastname
contacts[0].company String Contact’s company name
contacts[0].email String Contact’s email
contacts[0].externalLink String External link related to the contact
contacts[0].details Object Details of the contact
contacts[0].details.detail String Custom contact detail (optional)
contacts[0].lastModificationDate String Date of the most recent modification
contacts[0].externalServices Null
note String Actual note

  Refuse event

Sent when you mark a call as refused and you choose a reason for refusal.

Example response body:


{
  "id" : 6734581661011652939,
  "createdAt" : "2022-09-28T12:43:40.492+00:00",
  "type" : "REFUSE",
  "callId" : 8123042553126895905,
  "callDirection" : "OUTBOUND",
  "callDetails" : {
    "key" : "value",
    "numeric" : 7
  },
  "agentUsername" : "[email protected]",
  "userName" : "Name",
  "userSurname" : "Surname",
  "redirectMsisdn" : null,
  "contactMsisdn" : "+33980091888",
  "channelsMsisdn" : "+3225889300",
  "refuseReason" : {
    "id" : 3863418094773452145,
    "name" : "iVKwO",
    "type" : "CALL_PANEL"
  },
  "contacts" : [ {
    "id" : 7641651816143898703,
    "firstName" : "ELclzl",
    "lastName" : "qYyLqy",
    "company" : "KFpOxB",
    "externalLink" : "http://example.channels.app",
    "createdAt" : "2022-09-28T12:43:40.492+00:00",
    "lastModificationDate" : "2022-09-28T12:43:40.492+00:00",
    "source" : "WIDGET",
    "email" : "[email protected]",
    "msisdns" : [ "+33980091888", "+16475586333" ],
    "details" : {
      "detail" : "HGQJoN"
    },
    "externalServices" : null
  } ]
}
Response results
Path Type Description
id Number Contact event id
type String Type of event (always REFUSE)
createdAt String When event was created
agentUsername String Username (typically email) of the user who created event
userName String Name of the user who created event
userSurname String Surname of the user who created event
contacts Array All contacts related to the event
contacts[0].id Number Contact id
contacts[0].createdAt String Contact’s import date
contacts[0].source String Import source
contacts[0].msisdns Array List of alternative phone numbers assigned to contact
contacts[0].firstName String Contact’s firstname
contacts[0].lastName String Contact’s lastname
contacts[0].company String Contact’s company name
contacts[0].email String Contact’s email
contacts[0].externalLink String External link related to the contact
contacts[0].details Object Details of the contact
contacts[0].details.detail String Custom contact detail (optional)
contacts[0].lastModificationDate String Date of the most recent modification
contacts[0].externalServices Null
callId Number Call id during which the refusal happened
callDirection String Type of call, in this scenario it will always be OUTBOUND
contactMsisdn String Contact’s phone number
channelsMsisdn String Phone number assigned to the agent when the call happened
refuseReason.id Number Refuse reason’s id
refuseReason.name String Refuse reason’s name
refuseReason.type String Type of refuse reason (MOBILE or WIDGET)
callDetails Object Additional information related to the call