Introduction
Welcome to the Voxloud API reference! You can use our API key to access Voxloud API endpoints.
At the moment we don't offer specific language bindings but we offer a REST API with webhooks in order to rapidly work with our API. JSON is the data exchange format used in all endpoints.
Authentication
To authenticate and authorize every call, you must provide a specific HTTP header in every API request:
In this way you can pass the correct header with each request
curl -X GET "https://developer.voxloud.com/api/v1/some_call" -H "Voverc-Auth: your_api_key"
Voverc-Auth: your_api_key
Validate authentication
To validate your authentication key you can call /validate-auth endpoint which will return related company name and email if key is valid, HTTP 401 otherwise.
HTTP Request
POST https://developer.voxloud.com/api/v1/validate-auth
curl -X POST "https://developer.voxloud.com/api/v1/validate-auth" -H "Voverc-Auth: your_api_key"
It returns JSON structured like this:
{
"name": "company name",
"email": "administrator email"
}
Contacts API
Contact section of the API allows to create and manage your company contact resources in Voxloud.
Create contact
This endpoint creates a contact
HTTP Request
POST https://developer.voxloud.com/api/v1/contacts
This request creates a contact
curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
-d '{"first_name":"John","last_name":"Doe","primary_phone":"+390312345678","phones":["+390387654321"],"primary_email":"[email protected]","emails":["[email protected]"],"company_name":"John&Associates","job_title":"CEO","website":"www.johna.com","crm_name":"Voxloud","crm_contact_url":"https://www.crm.com/contacts/profile/1"}'
"https://developer.voxloud.com/api/v1/contacts"
It returns JSON structured like this:
{
"id" : "54db43f0-7d1c-11fd-8149-bdf161b05c48",
"first_name" : "John",
"last_name" : "Doe",
"primary_phone" : "+390312345678",
"phones" : [
"+390387654321"
],
"primary_email" : "[email protected]",
"emails" : [
"[email protected]"
],
"company_name" : "John & Associates",
"job_title" : "CEO",
"website" : "www.johna.com",
"crm_name" : "Voxloud",
"crm_contact_url" : "https://www.crm.com/contacts/profile/1",
"created_at" : "2022-12-27T14:42:37+01:00",
"updated_at" : "2022-12-27T14:42:37+01:00"
}
Request object
Property | Type | Required | Description |
---|---|---|---|
first_name | string | true | Contact first name |
last_name | string | false | Contact last name |
primary_phone | string | true | Contact primary phone number, must be in e164 format |
phones | array[string] | false | Contact secondary phone numbers, must be in e164 format |
primary_email | string | false | Contact primary email |
emails | array[string] | false | Contact secondary emails |
company_name | string | false | Contact company name |
job_title | string | false | Contact job title |
website | string | false | Contact company website |
crm_name | string | false | name of CRM where contact is from, will be set to Voxloud if not specified |
crm_contact_url | string | false | Contact URL which points to the contact profile in CRM portal |
Response object
Property | Type | Description |
---|---|---|
id | string | Contact identifier |
first_name | string | Contact first name |
last_name | string | Contact last name |
primary_phone | string | Contact primary phone number in e164 format |
phones | array[string] | Contact secondary phone numbers in e164 format |
primary_email | string | Contact primary email |
emails | array[string] | Contact secondary emails |
company_name | string | Contact company name |
job_title | string | Contact job title |
website | string | Contact company website |
crm_name | string | Name of CRM where contact is from |
crm_contact_url | string | Contact URL which points to the contact profile in CRM portal |
created_at | datetime | Contact created date in ISO-8601 format |
updated_at | datetime | Contact updated date in ISO-8601 format |
Update contact
This endpoint updates a contact
HTTP Request
POST https://developer.voxloud.com/api/v1/contacts/${id}
This request updates a contact
curl -X PUT -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
-d '{"first_name":"John","last_name":"Doe","primary_phone":"+390312345678","phones":["+390387654321","+390387654323"],"primary_email":"[email protected]","emails":["[email protected]"],"company_name":"John&Associates","job_title":"CEO","website":"www.johna.com","crm_name":"Voxloud","crm_contact_url":"https://www.crm.com/contacts/profile/1"}'
"https://developer.voxloud.com/api/v1/contacts/54db43f0-7d1c-11fd-8149-bdf161b05c48"
It returns JSON structured like this:
{
"id" : "54db43f0-7d1c-11fd-8149-bdf161b05c48",
"first_name" : "John",
"last_name" : "Doe",
"primary_phone" : "+390312345678",
"phones" : [
"+390387654321",
"+390387654323"
],
"primary_email" : "[email protected]",
"emails" : [
"[email protected]"
],
"company_name" : "John & Associates",
"job_title" : "CEO",
"website" : "www.johna.com",
"crm_name" : "Voxloud",
"crm_contact_url" : "https://www.crm.com/contacts/profile/1",
"created_at" : "2022-12-27T14:42:37+01:00",
"updated_at" : "2022-12-27T14:42:37+01:00"
}
Request object
Property | Type | Required | Description |
---|---|---|---|
first_name | string | true | Contact first name |
last_name | string | false | Contact last name |
primary_phone | string | true | Contact primary phone number, must be in e164 format |
phones | array[string] | false | Contact secondary phone numbers, must be in e164 format |
primary_email | string | false | Contact primary email |
emails | array[string] | false | Contact secondary emails |
company_name | string | false | Contact company name |
job_title | string | false | Contact job title |
website | string | false | Contact company website |
crm_name | string | false | name of CRM where contact is from, will be set to Voxloud if not specified |
crm_contact_url | string | false | Contact URL which points to the contact profile in CRM portal |
Response object
Property | Type | Description |
---|---|---|
id | string | Contact identifier |
first_name | string | Contact first name |
last_name | string | Contact last name |
primary_phone | string | Contact primary phone number in e164 format |
phones | array[string] | Contact secondary phone numbers in e164 format |
primary_email | string | Contact primary email |
emails | array[string] | Contact secondary emails |
company_name | string | Contact company name |
job_title | string | Contact job title |
website | string | Contact company website |
crm_name | string | Name of CRM where contact is from |
crm_contact_url | string | Contact URL which points to the contact profile in CRM portal |
created_at | datetime | Contact created date in ISO-8601 format |
updated_at | datetime | Contact updated date in ISO-8601 format |
Search Contacts
This endpoint allows to search contacts by the set of parameters, like first name or phone number.
HTTP Request
GET https://developer.voxloud.com/api/v1/contacts
This request allows to search contacts by the set of parameters, like first name or phone number.
curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
"https://developer.voxloud.com/api/v1/contacts?offset=350&limit=25&first_name=jOhN&last_name=dOe&email=j.doe0&phone=678"
It returns JSON structured like this:
{
"data" : [
{
"id" : "54db43f0-7d1c-11fd-8149-bdf161b05c48",
"first_name" : "John",
"last_name" : "Doe",
"primary_phone" : "+390312345678",
"phones" : [
"+390387654321"
],
"primary_email" : "[email protected]",
"emails" : [
"[email protected]"
],
"company_name" : "John & Associates",
"job_title" : "CEO",
"website" : "www.johna.com",
"crm_name" : "Voxloud",
"crm_contact_url" : "https://www.crm.com/contacts/profile/1",
"created_at" : "2022-12-27T14:42:37+01:00",
"updated_at" : "2022-12-27T14:42:37+01:00"
},
{
"id" : "54db43f0-7d1c-11fd-8149-bdf161b05c49",
"first_name" : "Maria",
"last_name" : "Rosi",
"primary_phone" : "+390312345637",
"phones" : [
"+390387654322"
],
"primary_email" : "[email protected]",
"emails" : [
"[email protected]"
],
"company_name" : "Maria & Associates",
"job_title" : "CEO",
"website" : "www.maria.com",
"crm_name" : "Voxloud",
"crm_contact_url" : "https://www.crm.com/contacts/profile/2",
"created_at" : "2022-12-28T14:42:37+01:00",
"updated_at" : "2022-12-28T14:42:37+01:00"
}
],
"has_next" : false
}
Query params
Property | Type | Required | Description |
---|---|---|---|
first_name | string | false | Contact full or partial first name |
last_name | string | false | Contact full or partial last name |
phone | string | false | Contact full or partial phone number, must be in e164 format |
string | false | Contact full or partial email | |
offset | string | false | Must be positive value. Default value is 0 |
limit | string | false | Must be more than 0 and less than or equal to 100. Default value is 20 |
Response object
Property | Type | Description |
---|---|---|
data | array[objects] | List of found contacts |
has_next | boolean | Indicates is there at least 1 more contact after requested page |
Get a contact
This endpoint returns an existing contact
HTTP Request
GET https://developer.voxloud.com/api/v1/contacts/${id}
This request returns an existing contact
curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
"https://developer.voxloud.com/api/v1/contacts/54db43f0-7d1c-11fd-8149-bdf161b05c48"
It returns JSON structured like this:
{
"id" : "54db43f0-7d1c-11fd-8149-bdf161b05c48",
"first_name" : "John",
"last_name" : "Doe",
"primary_phone" : "+390312345678",
"phones" : [
"+390387654321"
],
"primary_email" : "[email protected]",
"emails" : [
"[email protected]"
],
"company_name" : "John & Associates",
"job_title" : "CEO",
"website" : "www.johna.com",
"crm_name" : "Voxloud",
"crm_contact_url" : "https://www.crm.com/contacts/profile/1",
"created_at" : "2022-12-27T14:42:37+01:00",
"updated_at" : "2022-12-27T14:42:37+01:00"
}
Response object
Property | Type | Description |
---|---|---|
id | string | Contact identifier |
first_name | string | Contact first name |
last_name | string | Contact last name |
primary_phone | string | Contact primary phone number in e164 format |
phones | array[string] | Contact secondary phone numbers in e164 format |
primary_email | string | Contact primary email |
emails | array[string] | Contact secondary emails |
company_name | string | Contact company name |
job_title | string | Contact job title |
website | string | Contact company website |
crm_name | string | Name of CRM where contact is from |
crm_contact_url | string | Contact URL which points to the contact profile in CRM portal |
created_at | datetime | Contact created date in ISO-8601 format |
updated_at | datetime | Contact updated date in ISO-8601 format |
Delete contact
This endpoint removes an existing contact
HTTP Request
DELETE https://developer.voxloud.com/api/v1/contacts/${id}
This request deletes existing contact
curl -X DELETE -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
"https://developer.voxloud.com/api/v1/contacts/54db43f0-7d1c-11fd-8149-bdf161b05c48"
Users API
This API allows you query users
Get all users
This endpoint returns all users
HTTP Request
GET https://developer.voxloud.com/api/v2/users
curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" "https://developer.voxloud.com/api/v2/users"
It returns JSON structured like this:
[
{
"id" : "facbb7fe-f845-11ee-b19b-960000128e6c",
"first_name" : "John",
"last_name" : "Smith",
"extension_number" : 101,
"outbound_cli" : {
"outbound_did" : {
"number" : "+390112121212",
"label" : "Main office"
},
"available_dids" : [
{
"number" : "+390112121212",
"label" : "Main office"
},
{
"number" : "+3943212332432",
"label" : "Customer support"
},
{
"number" : "+3902421321222",
"label" : "Secondary office"
}
]
}
},
{
"id": "facc2109-f845-11ee-b99b-960000128e6c",
"first_name": "Federico",
"last_name": "Support",
"extension_number": 102,
"outbound_cli": {
"outbound_did": {
"number" : "+3943212332432",
"label" : "Customer support"
},
"available_dids": [
{
"number" : "+3943212332432",
"label" : "Customer support"
}
]
}
}
]
Response object
Property | Type | Description |
---|---|---|
id | string | User identifier |
first_name | string | User first name |
last_name | string | User last name |
extension_number | integer | User's extension number |
outbound_cli | OutboundCli | User's outbound numbers configuration |
OutboundCli
Property | Type | Description |
---|---|---|
outbound_did | Did | Currently selected outbound number |
available_dids | array[Did] | All available outbound numbers |
Did
Property | Type | Description |
---|---|---|
number | string | Phone number (international format) |
label | string | Phone number label |
Webhook subscriptions API
This API allows you to be notified in real-time via webhooks whenever events occur, allowing you to integrate your system with Voxloud, for example by showing detailed contact information when an incoming call arrives. In order to correctly setup this mechanism you need to configure a webhook subscription before.
Create a webhook subscription
This endpoint creates a webhook subscription
HTTP Request
POST https://developer.voxloud.com/api/v1/webhook-subscriptions
This request setups a notification on endpoint
http://my_endpoint.domain
whenCALL_INCOMING
event occurs
curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
-d '{"callback_url":"http://my_endpoint.domain","event_type":"CALL_INCOMING","notification_email":"[email protected]"}'
"https://developer.voxloud.com/api/v1/webhook-subscriptions"
It returns JSON structured like this:
{
"id": "119a7b3d-00b9-4445-808a-a69676f86763",
"enabled": true,
"event_type": "CALL_INCOMING",
"failed_count": 0,
"callback_url": "http://my_endpoint.domain",
"notification_email": "[email protected]"
}
Request object
Property | Required | Description |
---|---|---|
callback_url | true | It is the URL that will be invoked via webhook on every event |
event_type | true | Can be one of the following values: FAX_CALL, PHONE_CALL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP |
notification_email | false | Email that will be used for notifications if your subscription become disabled |
Response object
Property | Description |
---|---|
id | A unique identifier for the subscription |
callback_url | It is the URL that will be invoked via webhook on every event |
event_type | Can be one of the following values: FAX_CALL, PHONE_CALL, CLICK_TO_CALL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP |
failed_count | Number of failed attempts |
last_error | Last occurred error |
notification_email | Email that will be used for notifications if your subscription become disabled |
Update a webhook subscription
This endpoint updates an existing webhook subscription
HTTP Request
PUT https://developer.voxloud.com/api/v1/webhook-subscriptions/${id}
curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
-d '{"id":"119a7b3d-00b9-4445-808a-a69676f86763","enabled":true,"callback_url":"http://my_endpoint.domain","event_type":"CALL_ANSWERED"}'
"https://developer.voxloud.com/api/v1/webhook-subscriptions/119a7b3d-00b9-4445-808a-a69676f86763"
It returns JSON structured like this:
{
"id": "119a7b3d-00b9-4445-808a-a69676f86763",
"enabled": true,
"event_type": "CALL_ANSWERED",
"failed_count": 0,
"callback_url": "http://my_endpoint.domain",
"notification_email": "[email protected]"
}
Request object
Property | Required | Description |
---|---|---|
id | true | A unique identifier for the subscription |
callback_url | true | It is the URL that will be invoked via webhook on every event |
event_type | true | Can be one of the following values: FAX_CALL, PHONE_CALL, CLICK_TO_CALL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP |
enabled | false | Boolean to enable / disable subscription |
notification_email | false | Email that will be used for notifications if your subscription become disabled |
Response object
Property | Description |
---|---|
id | A unique identifier for the subscription |
callback_url | It is the URL that will be invoked via webhook on every event |
event_type | Can be one of the following values: FAX_CALL, PHONE_CALL, CLICK_TO_CALL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP |
enabled | Boolean to enable / disable subscription |
failed_count | Number of failed attempts |
last_error | Last occurred error |
notification_email | Email that will be used for notifications if your subscription become disabled |
Get webhook subscriptions
This endpoint returns all the existing webhook subscriptions
HTTP Request
GET https://developer.voxloud.com/api/v1/webhook-subscriptions
curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
"https://developer.voxloud.com/api/v1/webhook-subscriptions"
It returns JSON structured like this:
[
{
"id": "119a7b3d-00b9-4445-808a-a69676f86763",
"event_type": "CALL_INCOMING",
"failed_count": 0,
"enabled": true,
"callback_url": "http://my_endpoint.domain",
"notification_email": "[email protected]"
},
{
"id": "f98b8c5d-4935-4e32-b6e4-490687c7f14d",
"type": "CALL_ANSWERED",
"failed_count": 0,
"enabled": true,
"callback_url": "http://my_endpoint.domain",
"notification_email": "[email protected]"
},
{
"id": "9cf8e5e7-d32a-4fc9-bc4a-1c2c9f2aa82d",
"type": "CALL_HANGUP",
"failed_count": 0,
"enabled": true,
"callback_url": "http://my_endpoint.domain",
"notification_email": "[email protected]"
}
]
Response object
An array of the following objects:
Property | Description |
---|---|
id | A unique identifier for the subscription |
callback_url | It is the URL that will be invoked via webhook on every event |
event_type | Can be one of the following values: FAX_CALL, PHONE_CALL, CLICK_TO_CALL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP |
enabled | Boolean to enable / disable subscription |
failed_count | Number of failed attempts |
last_error | Last occurred error |
notification_email | Email that will be used for notifications if your subscription become disabled |
Get call webhook subscription
This endpoint returns an existing webhook subscription
HTTP Request
GET https://developer.voxloud.com/api/v1/webhook-subscriptions/${id}
curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
"https://developer.voxloud.com/api/v1/webhook-subscriptions/119a7b3d-00b9-4445-808a-a69676f86763"
It returns JSON structured like this:
{
"id": "119a7b3d-00b9-4445-808a-a69676f86763",
"event_type": "CALL_INCOMING",
"failed_count": 0,
"enabled": true,
"callback_url": "http://my_endpoint.domain",
"notification_email": "[email protected]"
}
Response object
Property | Description |
---|---|
id | A unique identifier for the subscription |
callback_url | It is the URL that will be invoked via webhook on every event |
event_type | Can be one of the following values: FAX_CALL, PHONE_CALL, CLICK_TO_CALL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP |
enabled | Boolean to enable / disable subscription |
failed_count | Number of failed attempts |
last_error | Last occurred error |
notification_email | Email that will be used for notifications if your subscription become disabled |
Delete a webhook subscription
This endpoint removes an existing webhook subscription
HTTP Request
DELETE https://developer.voxloud.com/api/v1/webhook-subscriptions/${id}
curl -X DELETE -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
"https://developer.voxloud.com/api/v1/webhook-subscriptions/119a7b3d-00b9-4445-808a-a69676f86763"
Webhooks
On occurrence of specific events on our platform, we can call your system through webhooks mechanism. You will receive a payload that helps you integrating your application with Voxloud. You need to setup a webhook subscription to receive these webhooks.
Every webhook that is sent has the following structure:
{
"timestamp": 1523025126000,
"type": "CALL_STARTED",
"data": {
"timestamp": 1523025126000,
"destinationNumber": "102",
"destinationName": "User2 User2",
"originatorNumber": "101",
"originatorName": "User1 User1",
"callId": "9cb33f1b427c4d8983a064f0bd68be95",
"type": "STARTED",
"userExtension": 101
},
"pbx_id": 117
}
The fields timestamp
, type
, and pbx_id
are common to every webhook, while the data
payload varies depending on the event type. All the event types are described in the following sections.
Phone call events
These webhooks are sent in real-time on occurence of some conditions on phone calls. They are emitted in the following conditions:
- Inbound call
- Call start (outbound and internal)
- Answered call
- Call hangup
Property | Type | Description |
---|---|---|
timestamp | number | Event timestamp represented in milliseconds elapsed from 01/01/1970 (Unix Epoch) |
callId | string | Call identifier |
destinationNumber | string | The destination number (callee) expressed in e164 format |
destinationName | string | Name of the user as configured in the PBX |
originatorNumber | string | The caller number expressed in e164 format |
originatorName | string | The caller name (where allowed) or some other identification string as configured in the PBX |
type | string | Can be one of the following values: INCOMING, STARTED, ANSWERED, HANGUP |
userExtension | number | Extension of the user subject of the event |
Example of a JSON payload on an incoming call
{
"timestamp": 1512552226000,
"callId": "9cb33f1b427c4d8983a064f0bd68be95",
"destinationNumber": "+3912345678",
"destinationName": "Some User",
"originatorNumber": "+390687654321",
"originatorName": "Another User",
"type": "INCOMING",
"userExtension" : 101
}
Telephony events
These webhooks are sent at the end of a series of micro-events (e.g. at the end of a phone call lasted 2 minutes) and represent the CDR (Call Detail Record). A delay of some seconds is normally present from the last micro-event to the dispatch of these webhooks, due to the processing of some additional data (e.g. call recording, call cost, ...). They are emitted for the following events:
- Phone Call
- Fax
- Click to call
Phone call
A phone call event has the following payload:
Property | Type | Description |
---|---|---|
timestamp | number | Event timestamp represented in milliseconds elapsed from 01/01/1970 (Unix Epoch) |
callId | string | Call identifier |
destinationNumber | string | The destination number (callee) expressed in e164 format |
destinationName | string | Name of the user as configured in the PBX |
originatorNumber | string | The caller number expressed in e164 format |
originatorName | string | The caller name (where allowed) or some other identification string as configured in the PBX |
answererName | string | The answerer name (where allowed) or some other identification string as configured in the PBX |
answererNumber | string | The answerer number expressed in e164 format |
maskCallerNumber | boolean | True if the caller number was masked |
type | string | Can be one of the following values: PHONE_CALL, FAX_CALL, CLICK_TO_CALL |
direction | string | Can be one of the following values: INTERNAL, OUTBOUND, INBOUND |
accountId | string | PBX unique identifier |
lastEvent | string | Last event occurred on a phone call. Can be one of the following values: CALL_REQUEST, CALL_STARTED, CALL_CANCELED_BY_ORIGINATOR, CALL_ANSWERED, CALL_TERMINATED, CALL_REJECTED, CALL_LOST_LOSE_RACE, CALL_LOST_NO_ANSWER, CALL_TRANSFERRED, CALL_LOST_USER_BUSY |
duration | number | Duration of the phone call in seconds (ringTime included) |
ringTime | number | Duration of the call before first answerer action |
archived | boolean | True if this event has been marked as archived |
recorded | boolean | True if this phone call has an associated call recording |
recordingUrl | string | The URL of the recorded media (if phone call recording is enabled) |
voicemail | boolean | True if this event has a voicemail |
labels | array (string) | Custom labels assigned to the call |
ruleNames | array (string) | Names of the IVR rules triggered during the call |
contactCrm | string | Name of the CRM contact was found in |
contactCrmUrl | string | URL to the contact on CRM |
crmLogo | string | URL to the CRM logo |
transcription | string | Transcription of the call (length <= 65,535) |
summary | string | Short summary of the call (length <= 3500) |
sentiment_score | number | Numeric representation of call sentiment (0 - 100) |
Example of a JSON payload on an incoming call
{
"id": 8395,
"type": "PHONE_CALL",
"accountId": "faffd4879c2b686fe9c5fb1673ce2800",
"direction": "INTERNAL",
"timestamp": 1523369486000,
"originatorName": "User1 User2",
"originatorNumber": "101",
"destinationName": "User2 User2",
"destinationNumber": "102",
"answererName": "User2 User2",
"answererNumber": "102",
"maskCallerNumber" : false,
"lastEvent": "CALL_TERMINATED",
"duration": 4,
"ringTime": 1,
"archived": false,
"callId": "1734bfbbd5dc4a9c8de1d2e5235e6389",
"recorded": true,
"recordingUrl": "https://vmediaproduction.s3.eu-central-1.amazonaws.com/213/call_recordings/call_recording_1734bfbbd5dc4a9c8de1d2e5235e6389.mp3",
"voicemail": true,
"voicemail_url": "https://vmediaproduction.s3.eu-central-1.amazonaws.com/213/call_recordings/vm_1734bfbbd5dc4a9c8de1d2e5235e6389.mp3",
"labels" : [ "label1", "label2" ],
"ruleNames" : [ "IVRRule1", "IVRRule2" ],
"contactCrm" : "Hubspot",
"contactCrmUrl" : "https://app.hubspot.com/contacts/1111111/contact/1111111",
"crmLogo" : "https://fake.cloudfront.net/image/logos/fake-hubspot.png",
"transcription": "Workers who telecommute tend to be more aware of cybersecurity threats than those who spend most of their time in a physical office and are more likely to take action to ward them off, according to our new peer-reviewed study.",
"summary": "A study has found that remote workers tend to be more aware of cybersecurity threats and are more likely to take action to protect against them compared to in-office workers.",
"sentiment_score": 73
}
Fax
A fax event has the following payload:
Property | Type | Description |
---|---|---|
timestamp | number | Event timestamp represented in milliseconds elapsed from 01/01/1970 (Unix Epoch) |
id | number | Identifier of the fax |
recipient | string | The recipient number expressed in e164 format |
sender | string | The sender number expressed in e164 format |
direction | string | The direction of the fax (inbound, outbound) |
attachment_url | string | The URL of the fax attachment |
total_pages | number | The number of total page of the fax attachment |
description | string | The fax description (only present if outbound faxes) |
Example of a JSON payload on an outbound fax
{
"id": 1234,
"timestamp": 1523369486000,
"direction": "outbound",
"sender": "39123456789",
"recipient": "39987654321",
"attachment_url": "https://prod-fax-service.s3.eu-central-1.amazonaws.com/1/1/fax_2011_5_11_11_32_30.pdf",
"total_pages": 4,
"description": "A fax description"
}
Click to call
A click to call event has the following payload:
Property | Type | Description |
---|---|---|
timestamp | number | Event timestamp represented in milliseconds elapsed from 01/01/1970 (Unix Epoch) |
id | number | Identifier of the click to call event |
callId | string | Call identifier |
destinationNumber | string | The destination number (callee) expressed in e164 format |
destinationName | string | Name of the user as configured in the PBX |
originatorNumber | string | The caller number expressed in e164 format |
originatorName | string | The caller name (where allowed) or some other identification string as configured in the PBX |
clickToCallType | string | Can be one of the following values: EXTENSION, CONTACT |
direction | string | Can be one of the following values: INTERNAL, OUTBOUND, INBOUND |
accountId | string | PBX unique identifier |
duration | number | Duration of the phone call in seconds |
ringTime | number | Duration of the call before first answerer action |
archived | boolean | True if this event has been marked as archived |
recorded | boolean | True if this phone call has an associated call recording |
recordingUrl | string | The URL of the recorded media (if phone call recording is enabled) |
labels | array (string) | Custom labels assigned to the call |
ruleNames | array (string) | Names of the IVR rules triggered during the call |
contactCrm | string | Name of the CRM contact was found in |
contactCrmUrl | string | URL to the contact on CRM |
crmLogo | string | URL to the CRM logo |
transcription | string | Transcription of the call (length <= 65,535) |
summary | string | Short summary of the call (length <= 3500) |
sentiment_score | number | Numeric representation of call sentiment (0 - 100) |
Example of a JSON payload on a click to call
{
"id": 517,
"type": "CLICK_TO_CALL",
"accountId": "2b7c39f77b46eb2899fc39d0b1bd4329",
"direction": "OUTBOUND",
"timestamp": 1569525122000,
"originatorName": "Pinco Pallino",
"originatorNumber": "390663971096",
"destinationName": "393287035654",
"destinationNumber": "393287035654",
"duration": 40,
"ringTime": 1,
"queueCallId": "303b553038d9847c93ca59ebd310225fae95-clicktocall",
"clickToCallType": "EXTENSION",
"archived": false,
"callId": "303b553038d9847c93ca59ebd310225fae95-clicktocall",
"recorded": true,
"recordingUrl": "https://voxloud.s3.eu-central-1.amazonaws.com/6/call_recordings/call_recording_303b553038d9847c93ca59ebd310225fae95-clicktocall.mp3",
"labels" : [ "label1", "label2" ],
"ruleNames" : [ "IVRRule1", "IVRRule2" ],
"contactCrm" : "Hubspot",
"contactCrmUrl" : "https://app.hubspot.com/contacts/1111111/contact/1111111",
"crmLogo" : "https://fake.cloudfront.net/image/logos/fake-hubspot.png",
"transcription": "Workers who telecommute tend to be more aware of cybersecurity threats than those who spend most of their time in a physical office and are more likely to take action to ward them off, according to our new peer-reviewed study.",
"summary": "A study has found that remote workers tend to be more aware of cybersecurity threats and are more likely to take action to protect against them compared to in-office workers.",
"sentiment_score": 73
}
Telephony events API
This API allows you to query for telephony events and get their details. This includes phone calls and fax calls
Query
This endpoint gives the possibility to perform paged queries on telephony events. The result can be returned as application/json
or text/csv
. This is handled by specifying the Accept
header with the desired representation. By default, JSON is returned.
HTTP Request
POST https://developer.voxloud.com/api/v1/telephony-events
This request fetches all events related to number 06123456789, between dates 2018-03-11T07:00:00.000Z and 2018-04-16T07:00:00.000Z
curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
-d '{"date_time_from":"2018-03-11T07:00:00.000Z","date_time_to":"2018-04-16T07:00:00.000Z", "number":"06123456789"}'
"https://developer.voxloud.com/api/v1/telephony-events?sort=timestamp,desc&size=30&page=0"
It returns JSON structured like this:
{
"content": [
{
"id": 8563,
"type": "FAX_CALL",
"accountId": "faffd4879c2b686fe9c5fb1673ce2800",
"direction": "INBOUND",
"timestamp": "2018-05-15T15:47:03.000+0000",
"originatorName": "anonymous",
"originatorNumber": "anonymous",
"destinationName": "3907331980093-fax-caller-id-name",
"destinationNumber": "3907331980093",
"callId": "fae5d4a5-d2f9-1236-57a7-06f6192f6ec4",
"duration": 32,
"archived": false
},
{
"id": 8536,
"type": "PHONE_CALL",
"accountId": "faffd4879c2b686fe9c5fb1673ce2800",
"direction": "INBOUND",
"timestamp": "2018-05-07T13:47:49.000+0000",
"originatorName": "Emanuele De Amicis",
"originatorNumber": "0697631539",
"destinationName": "3907761790162",
"destinationNumber": "3907761790162",
"lastEvent": "CALL_CANCELED_BY_ORIGINATOR",
"duration": 7,
"archived": false,
"callId": "125113c1-cca0-1236-9ea3-06f6192f6ec4",
"recorded": false,
"voicemail": false
}
],
"last": true,
"totalElements": 8,
"totalPages": 1,
"sort": [
{
"direction": "DESC",
"property": "timestamp",
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": false,
"descending": true
}
],
"first": true,
"numberOfElements": 8,
"size": 30,
"number": 0
}
Request object
Property | Required | Description |
---|---|---|
number | false | Telephone number to fetch events related to it |
date_time_from | false | Temporal interval start in ISO8601 format with timezone (example for UTC = 2021-01-01T00:00:00.000Z) |
date_time_to | false | Temporal interval end in ISO8601 format with timezone (example for Europe/Rome = 2021-01-01T00:00:00.000+01:00) |
Request parameters
Parameter | Required | Description |
---|---|---|
sort | false | The property used for sorting the query results. The syntax should be like: sort=timestamp,desc where timestamp is the name of the property and desc is indicating descending sorting |
size | false | The number of elements in a query page |
page | false | The number of requested query page |
Response object (JSON)
Property | Description |
---|---|
content | The array of query elements (see webhooks) for element field details |
last | Indicates if this is the last page of the result set |
totalElements | The total number of elements in the result set |
totalPages | The number of pages in the result set |
sort.property | The property name used to sort the result set |
sort.ascending | Indicates if the result set is sorted ascending |
sort.descending | Indicates if the result set is sorted descending |
first | true if this is the first page in the result set |
numberOfElements | Number of elements in this page |
size | The size of the page |
number | The number of page |
Get by ID
This endpoint returns a telephony event using its ID
HTTP Request
GET https://developer.voxloud.com/api/v1/telephony-events/${id}
curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
"https://developer.voxloud.com/api/v1/telephony-events/11231"
It returns JSON structured like the ones described in section webhooks
Get by callId
This endpoint returns a telephony event using its callId
HTTP Request
GET https://developer.voxloud.com/api/v1/telephony-events?callId=${callId}
curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
"https://developer.voxloud.com/api/v1/telephony-events?callId=aabbccddeeff123456"
It returns JSON structured like the ones described in section webhooks
Click-to-call API
This feature allows you to generate click-to-call resources that can be invoked, giving a contact number and creating a phone call from the provided contact to an extension you have pre-determined. For example, this mechanism can be used to call back users visiting your site, allowing them to be put directly in contact with your PBX extensions. Important: click-to-call objects should be reused after their creation as there is a limit on the amount of click-to-call objects that can be created and it is dependent on the sum of number of users (extensions) and groups. For example, if your PBX has 3 users and 2 groups, you will be allowed to create a total of 5 click-to-call objects.
Create a click-to-call
This endpoint creates a click-to-call resource
HTTP Request
POST https://developer.voxloud.com/api/v1/click-to-call
This request creates a click-to-call resource for extension
101
curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
-d '{"name":"support","extension":"101","outboundNumber":"+39123456789","dial_first":"contact"}'
"https://developer.voxloud.com/api/v1/click-to-call"
It returns JSON structured like this:
{
"id": "8ff3728fb5c5d9560e81c3c7080c3b95",
"name": "ctc-support",
"extension": "101",
"outboundNumber": "+390660786731",
"dial_first": "contact"
}
Request object
Property | Required | Description |
---|---|---|
name | true | Friendly name for the click-to-call resource |
extension | true | The extension to be called |
outboundNumber | true | The outbound number used to call the contact. It should match one of your PBX configured numbers |
dial_first | false | Indicates who will be called first. Allowed values are contact or extension . Default value: extension |
Response object
Property | Description |
---|---|
id | A unique identifier for the click-to-call resource |
extension | It is the URL that will be invoked via webhook on every phone call fact |
outboundNumber | true |
dial_first | Indicates who will be called first. Allowed values are contact or extension |
Get a click-to-call
This endpoint returns an existing click-to-call resource
HTTP Request
GET https://developer.voxloud.com/api/v1/click-to-call/${id}
curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
"https://developer.voxloud.com/api/v1/click-to-call/8ff3728fb5c5d9560e81c3c7080c3b95"
It returns JSON structured like this:
{
"id": "8ff3728fb5c5d9560e81c3c7080c3b95",
"name": "ctc_support",
"extension": "101",
"outboundNumber": "+390660786731",
"dial_first": "contact"
}
Response object
Property | Description |
---|---|
id | A unique identifier for the click-to-call resource |
extension | It is the URL that will be invoked via webhook on every phone call fact |
outboundNumber | true |
dial_first | Indicates who will be called first. Allowed values are contact or extension |
Get all click-to-call
This endpoint returns all existing click-to-call resources
HTTP Request
GET https://developer.voxloud.com/api/v1/click-to-call
curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
"https://developer.voxloud.com/api/v1/click-to-call"
It returns JSON structured like this:
[
{
"id": "8ff3728fb5c5d9560e81c3c7080c3b95",
"name": "ctc-support",
"extension": "101",
"outboundNumber": "+390660786731",
"dial_first": "contact"
},
{
"id": "7fad6102abe18759324cd292344aa3213",
"name": "ctc-marketing",
"extension": "102",
"outboundNumber": "+390660786731",
"dial_first": "contact"
}
]
Response object
An array of the following objects:
Property | Description |
---|---|
id | A unique identifier for the click-to-call resource |
extension | It is the URL that will be invoked via webhook on every phone call fact |
outboundNumber | true |
dial_first | Indicates who will be called first. Allowed values are contact or extension |
Delete a click-to-call
This endpoint removes an existing click-to-call resource
HTTP Request
DELETE https://developer.voxloud.com/api/v1/click-to-call/${id}
curl -X DELETE -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
"https://developer.voxloud.com/api/v1/click-to-call/8ff3728fb5c5d9560e81c3c7080c3b95"
Connect click-to-call
This endpoint setups a call between the extension indicated in the click-to-call resource and the provided contact. Depending on the value of the dial_first
field, the contact or the extension is called first.
HTTP Request
POST https://developer.voxloud.com/api/v1/click-to-call/${id}/connect
This request connects with a phone call contact
+39123456789
and extension101
curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
-d '{"contact":"+39987654321"}'
"https://developer.voxloud.com/api/v1/click-to-call/8ff3728fb5c5d9560e81c3c7080c3b95/connect"
It returns JSON structured like this:
{
"contact": "+39987654321"
}
Request object
Property | Required | Description |
---|---|---|
contact | true | Contact number in e164 format |
Response object
Property | Description |
---|---|
contact | Contact number in e164 format |
Errors
The Voxloud API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is not well-formed. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- The requested resource is not accessible with your credentials. |
404 | Not Found -- The specified resource could not be found. |
405 | Method Not Allowed -- You tried to access an endpoint with an invalid method. |
406 | Not Acceptable -- You requested a format that isn't JSON. |
429 | Too Many Requests -- You're doing too many requests! Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |