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" : 2602000571753960346,
"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) |
Contact is a basic object representing entity that you can call to.
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" : "2024-10-11T17:55:53.000+00:00",
"lastModificationDate" : "2024-10-11T17:55:53.191+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" : "2024-10-11T17:55:53.000+00:00",
"lastModificationDate" : "2024-10-11T17:55:53.208+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 |
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" : "2024-10-11T17:55:52.000+00:00",
"lastModificationDate" : "2024-10-11T17:55:52.219+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 |
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" : "2024-10-11T17:55:51.000+00:00",
"lastModificationDate" : "2024-10-11T17:55:50.867+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 |
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 |
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 |
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 |
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 |
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" : "2024-10-11T17:55:53.000+00:00",
"lastModificationDate" : "2024-10-11T17:55:52.794+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" : "2024-10-11T17:55:49.493+00:00",
"type" : "NOTE",
"agentUsername" : "[email protected]",
"name" : "John",
"surname" : "Doe",
"recordingAvailable" : false,
"note" : "test",
"callDetails" : { }
}, {
"id" : 5,
"contactId" : 13,
"createdAt" : "2024-10-11T17:55:49.188+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" : "2024-10-11T17:55:50.498Z",
"createdAt" : "2024-10-11T17:55:50.498Z",
"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 |
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" : "ZRTRw",
"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" : "2024-10-11T17:55:56.599Z",
"userId" : 52,
"status" : "UNBLOCKED",
"username" : "[email protected]",
"sameMsisdnEventsCount" : 2
}, {
"msisdn" : "+6499519999",
"eventDate" : "2024-10-11T17:55:56.513Z",
"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" : "2024-10-11T17:55:56.803Z",
"userId" : 53,
"status" : "UNBLOCKED",
"username" : "[email protected]"
}, {
"msisdn" : "+6499519999",
"eventDate" : "2024-10-11T17:55:56.795Z",
"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" : "+6499519999",
"eventDate" : "2024-10-11T17:55:56.013Z",
"userId" : 50,
"status" : "BLOCKED"
}, {
"msisdn" : "+16475586333",
"eventDate" : "2024-10-11T17:55:56.013Z",
"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" : "2024-10-11T17:55:56.299Z",
"userId" : 51,
"status" : "UNBLOCKED"
}, {
"msisdn" : "+16475586333",
"eventDate" : "2024-10-11T17:55:56.299Z",
"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: 695
[ {
"id" : 6612839249571917824,
"startDate" : "2024-10-10T17:55:48.098Z",
"finishDate" : "2024-10-10T17:55:48.098Z",
"answeredDate" : "2024-10-10T17:55:48.098Z",
"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,
"orders" : [ ],
"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/1838141769284708352 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: 691
{
"id" : 1838141769284708352,
"startDate" : "2024-10-10T17:55:47.811Z",
"finishDate" : "2024-10-10T17:55:47.811Z",
"answeredDate" : "2024-10-10T17:55:47.811Z",
"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,
"orders" : [ ],
"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.
Create a public link to the recording
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" : 2561208350457397248
}
Example response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 156
{
"callId" : 2561208350457397248,
"link" : "http://crazycall.com/recording-files/your-account-hash.crazycall.com/750069a3-850a-423a-a7aa-4a05f561ae06"
}
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. |
Get all links to public recordings
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" : 6950758770985576448,
"link" : "http://crazycall.com/recording-files/your-account-hash.crazycall.com/823302bd-c0e7-4853-b471-7ca1a6a9cb2f"
} ]
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. |
Delete public link to 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/cc8ba067-487e-481c-85f6-e0bf87480477 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. |
Create a link to recordings archive
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" : "2024-10-09T17:55:30.000Z",
"dateTo" : "2024-10-11T17:55:30.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/21085989-0f17-4f61-baba-96129c3e36b8",
"dateFrom" : "2024-10-09T17:55:30.000Z",
"dateTo" : "2024-10-11T17:55:30.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. |
Get all links to recordings archive
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/22619c60-3ca9-4e31-af21-47d3ee852d99",
"dateFrom" : "2024-10-09T17:55:30.000Z",
"dateTo" : "2024-10-11T17:55:30.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. |
Delete recordings archive link
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/92593b06-5d42-463e-87b6-7d2b32320f3a 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/2086832069200922624/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=2024-10-11T17%3A55%3A45.640Z 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. 2024-10-11T17:55:45.640Z) |
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_DGQQZJL",
"quantity" : 10,
"voiceBalanceSeconds" : 30000,
"discountPercentage" : 10,
"discountType" : "FOREVER",
"discountValid" : true,
"periodStart" : 1727805345,
"periodEnd" : 1730397345,
"destinationCountriesCount" : 90,
"cancelAtPeriodEnd" : false,
"planCurrency" : "USD",
"subscriptionPrice" : 9.5,
"discountDollars" : 10.0,
"trial" : false,
"planPrice" : 0.95
}
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=2024-10-06&dateUntil=2024-10-11&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.
| 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.
- Contact ID - ID of the given contact
- User - email address of the user
- Date - the time and date when the call was answered
- Phone number - the contact number that was called
- Connection time - time that it took to connect to the customer (expressed in seconds) along with the whole duration of the call
- Call time - call duration expressed in seconds
- Cost - the price you paid for the particular connection. An empty value means that this call was included in your monthly minutes package
- Direction - information regarding whether it was an outbound or an inbound call
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:
- 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.
- Webhook name - select a unique name you will identify your webhook by, like “Stats app notification”
- 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.
| status |
Description |
AUTOSCHEDULED |
Autoscheduled |
CLOSED |
Closed |
NOT_VERIFIED |
Not verified |
OPEN |
Open |
SCHEDULED |
Scheduled |
| 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" : 3741506589100777013,
"contact" : {
"id" : 7919174168139369122,
"firstName" : "hrdYqM",
"lastName" : "agqCdF",
"company" : "hoqwas",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:54.603+00:00",
"lastModificationDate" : "2024-10-11T17:55:54.603+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "KKRqDB"
},
"externalServices" : null
},
"msisdn" : "+48717221111",
"agentMsisdn" : "+14153661222",
"agentMsisdnId" : 8967415704577044698,
"startDate" : "2024-10-11T17:48:54.603+00:00",
"answeredDate" : "2024-10-11T17:50:54.603+00:00",
"length" : 180,
"agentId" : 3876687231786108283,
"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" : 8412230401523885164,
"contact" : {
"id" : 7849529188490109601,
"firstName" : "noMXyh",
"lastName" : "OzLOeW",
"company" : "qTTibU",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:54.721+00:00",
"lastModificationDate" : "2024-10-11T17:55:54.721+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "lxwMnM"
},
"externalServices" : null
},
"msisdn" : "+48717221111",
"agentMsisdn" : "+14153661222",
"agentMsisdnId" : 8383912994752981078,
"startDate" : "2024-10-11T17:48:54.721+00:00",
"answeredDate" : "2024-10-11T17:50:54.721+00:00",
"finishDate" : "2024-10-11T17:53:54.721+00:00",
"length" : 180,
"finishType" : "FINISHED_BY_AGENT",
"agentId" : 8140154860701897694,
"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" : 4180002825173472289,
"createdAt" : "2024-10-11T17:55:55.290+00:00",
"type" : "MSISDN_CONFIG_CHANGE",
"agentUsername" : "[email protected]",
"userName" : "Name",
"userSurname" : "Surname",
"newMsisdn" : "+14153661222",
"redirectMsisdn" : null,
"contacts" : [ {
"id" : 532553964936355080,
"firstName" : "EwLckh",
"lastName" : "ZviZRt",
"company" : "nzSsVT",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:55.290+00:00",
"lastModificationDate" : "2024-10-11T17:55:55.290+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "ApyhJV"
},
"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 |
Sent when you updated custom information about your contact
Example response body:
{
"id" : 8597123629286551800,
"createdAt" : "2024-10-11T17:55:53.901+00:00",
"type" : "CONTACT_DETAILS_CHANGE",
"agentUsername" : "[email protected]",
"userName" : "Name",
"userSurname" : "Surname",
"redirectMsisdn" : null,
"contacts" : [ {
"id" : 2924255337447852052,
"firstName" : "GQmoGf",
"lastName" : "VehuTL",
"company" : "KVACnA",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:53.901+00:00",
"lastModificationDate" : "2024-10-11T17:55:53.901+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "OnkVps"
},
"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 |
|
Sent when you removed a contact
Example response body:
{
"id" : 8733984145592791309,
"createdAt" : "2024-10-11T17:55:55.605+00:00",
"type" : "DELETE_CONTACT",
"agentUsername" : "[email protected]",
"userName" : "Name",
"userSurname" : "Surname",
"redirectMsisdn" : null,
"contacts" : [ {
"id" : 7844348996295204317,
"firstName" : "uWKGCY",
"lastName" : "pddivw",
"company" : "EVARml",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:55.605+00:00",
"lastModificationDate" : "2024-10-11T17:55:55.605+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "VYxsUj"
},
"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 |
|
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" : 2392314671153111387,
"createdAt" : "2024-10-11T17:55:54.417+00:00",
"type" : "FAILED_CONTACT",
"reason" : "VOICE_MAIL",
"callId" : 5197003479571157778,
"callDirection" : "OUTBOUND",
"callDetails" : {
"key" : "value",
"numeric" : 7
},
"agentUsername" : "[email protected]",
"userName" : "Name",
"userSurname" : "Surname",
"redirectMsisdn" : null,
"contactMsisdn" : "+33980091888",
"channelsMsisdn" : "+3225889300",
"contacts" : [ {
"id" : 1997992518068160328,
"firstName" : "hjAyeC",
"lastName" : "yNsMzG",
"company" : "NDZrTq",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:54.417+00:00",
"lastModificationDate" : "2024-10-11T17:55:54.417+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "kuisiZ"
},
"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 |
Sent when you created new contacts, e.g. through the API call
Example response body:
{
"id" : 3560512222968588707,
"createdAt" : "2024-10-11T17:55:55.013+00:00",
"type" : "IMPORT_CONTACT",
"agentUsername" : "[email protected]",
"userName" : "Name",
"userSurname" : "Surname",
"redirectMsisdn" : null,
"contacts" : [ {
"id" : 7377022050425829499,
"firstName" : "ISWxsW",
"lastName" : "Iinwhm",
"company" : "ZoPZbN",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:55.013+00:00",
"lastModificationDate" : "2024-10-11T17:55:55.013+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "RziWLv"
},
"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" : 142928921711550172,
"createdAt" : "2024-10-11T17:55:55.791+00:00",
"type" : "INCOMING_CALL_ANSWERED",
"customStatus" : "Incoming call",
"callId" : 548183783734031754,
"callDirection" : "INBOUND",
"callDetails" : {
"key" : "value",
"numeric" : 7
},
"agentUsername" : "[email protected]",
"userName" : "Name",
"userSurname" : "Surname",
"redirectMsisdn" : null,
"contactMsisdn" : "+33980091888",
"channelsMsisdn" : "+3225889300",
"contacts" : [ {
"id" : 1848560457244015794,
"firstName" : "MiqJls",
"lastName" : "hcfjDf",
"company" : "wJWxfs",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:55.791+00:00",
"lastModificationDate" : "2024-10-11T17:55:55.791+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "JeGSCQ"
},
"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" : 7212940633563882002,
"createdAt" : "2024-10-11T17:55:54.899+00:00",
"type" : "INCOMING_CALL_REDIRECTED",
"callId" : 9090443078538167900,
"callDirection" : "INBOUND",
"callDetails" : {
"key" : "value",
"numeric" : 7
},
"agentUsername" : "[email protected]",
"userName" : "Name",
"userSurname" : "Surname",
"redirectMsisdn" : "+48717221111",
"contactMsisdn" : "+33980091888",
"channelsMsisdn" : "+3225889300",
"contacts" : [ {
"id" : 2564336026613358888,
"firstName" : "VoawDx",
"lastName" : "itEndK",
"company" : "tMnhfb",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:54.899+00:00",
"lastModificationDate" : "2024-10-11T17:55:54.899+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "jUKlmV"
},
"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" : 6764389648728966998,
"createdAt" : "2024-10-11T17:55:54.008+00:00",
"type" : "INCOMING_CALL_NOT_ANSWERED",
"callId" : 6862286620691156093,
"callDirection" : "INBOUND",
"callDetails" : {
"key" : "value",
"numeric" : 7
},
"agentUsername" : "[email protected]",
"userName" : "Name",
"userSurname" : "Surname",
"redirectMsisdn" : null,
"contactMsisdn" : "+33980091888",
"channelsMsisdn" : "+3225889300",
"contacts" : [ {
"id" : 3629001859663889508,
"firstName" : "uUshhR",
"lastName" : "iifrhK",
"company" : "dSrUlr",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:54.008+00:00",
"lastModificationDate" : "2024-10-11T17:55:54.008+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "GAwjyv"
},
"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" : 6590124967999992602,
"contact" : {
"id" : 6620507839107648553,
"firstName" : "XjTinq",
"lastName" : "AvgIlJ",
"company" : "ObjLld",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:54.319+00:00",
"lastModificationDate" : "2024-10-11T17:55:54.319+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "eZcpuv"
},
"externalServices" : null
},
"msisdn" : "+48717221111",
"agentMsisdn" : "+14153661222",
"agentMsisdnId" : 7966984130874569254,
"startDate" : "2024-10-11T17:48:54.319+00:00",
"answeredDate" : "2024-10-11T17:49:54.319+00:00",
"finishDate" : "2024-10-11T17:53:54.319+00:00",
"length" : 0,
"finishType" : "FINISHED_BY_CLIENT",
"agentId" : 2318236923014984661,
"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" : 7786311398979413756,
"createdAt" : "2024-10-11T17:55:53.612+00:00",
"type" : "NOTE",
"agentUsername" : "[email protected]",
"userName" : "Name",
"userSurname" : "Surname",
"redirectMsisdn" : null,
"note" : "gIfnsqNjDfM",
"contacts" : [ {
"id" : 3861633975319032429,
"firstName" : "yWBUwp",
"lastName" : "ZvmtvO",
"company" : "tEISJz",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:53.612+00:00",
"lastModificationDate" : "2024-10-11T17:55:53.612+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "wCNRQm"
},
"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" : 7232049477507541468,
"createdAt" : "2024-10-11T17:55:55.411+00:00",
"type" : "REFUSE",
"callId" : 5382998719696220193,
"callDirection" : "OUTBOUND",
"callDetails" : {
"key" : "value",
"numeric" : 7
},
"agentUsername" : "[email protected]",
"userName" : "Name",
"userSurname" : "Surname",
"redirectMsisdn" : null,
"contactMsisdn" : "+33980091888",
"channelsMsisdn" : "+3225889300",
"refuseReason" : {
"id" : 8777676027961985279,
"name" : "nzgmU",
"type" : "CALL_PANEL"
},
"contacts" : [ {
"id" : 8437929693153284803,
"firstName" : "vLIvrZ",
"lastName" : "rmDbOz",
"company" : "cRsZCp",
"externalLink" : "http://example.channels.app",
"createdAt" : "2024-10-11T17:55:55.411+00:00",
"lastModificationDate" : "2024-10-11T17:55:55.411+00:00",
"source" : "WIDGET",
"email" : "[email protected]",
"msisdns" : [ "+33980091888", "+16475586333" ],
"details" : {
"detail" : "SQfjZQ"
},
"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 |
