NAV Navbar
http

Introduction

Welcome to the VozTelecom CRM API. You can use our API to integrate your CRM , ERP or any other enterprise system with VozTelecom's telephony service. The API is divided in events and requests.

Events inform you of the development of calls in your cloud telephony system. For instance the arrival of an incoming call, the stablishment of a call or the end of it. Events are sent from VozTelecom to you via HTTP/S. You need to implement an endpoint to manage these events. The URL of your endpoint as well as other configuration paramenters can be set by the request calls in this API.

Requests are sent from you to VozTelecom. They let you configure the API, manage ongoing calls and trigger new ones.

In order to use this API you must be customer of VozTelecom and subscribe the CRM Integration service. Go to VozTelecom for more information.

Authentication

The API requests are authorized with an Authentication token sent along with the request. All HTTP Requests should include an authentication header like the following

Authorization: VTCRM-Basic 83isocjid5hyd02sdjiembslw323

Failure to provide a valid authentication token will lead to a 401 HTTP Response

Requests API

At this time the requests API has four methods: the API configuration method, the call triggering method, the call drop method and the call redirect method. By using the configuration method you can configure how the events API will notify you of the communication events that take place in realtime. By using the call triggering method you can start a call between one of the extensions in your cloud communications system and another extension or geographical number, fixed, mobile, national or international. The method supports the specification of callback parameters that will allow you to correlate the calls requested with the events reported by the Events API. Established calls can be dropped with the Call Drop method. Incoming calls, whether established or in alerting state, can be also cold forwarded using the Redirect Call Method.

API Configuration method

Use this request to configure the events API. You can configure the URL where you expect to receive the notifications of the communication events as well as the HTTP method of the notification requests, the headers and the parameters.

HTTP Request

POST https://config.work.oigaa.com/vtcrm/api/configure

curl "https://config.work.oigaa.com/vtcrm/api/configure"
  -H "Authorization: VTCRM-Basic 83isocjid5hyd02sdjiembslw323"

The above command takes a JSON payload structured like this:

  {
    "events_callback_url": "https://example.com/vtcrm/callback",
    "events_callback_headers": {
                "X-A-Header" : "A header value",    
                "X-Another-Header" : "Another header value" 
                },
    "events_callback_parameters": {
                "a_parameter" : "A parameter value",    
                "another_parameter" : "Another parameter value" 
                },
    "allowed_ip_address" : ["193.22.119.28","218.32.3.0/32"]
  }

Query Parameters

Parameter Mandatory Description
events_callback_url yes The URL of the events endpoint where you expect to receive the event notifications. Standard HTTP response codes are expected.
events_callback_headers no A json object whose attribute names/values will be sent as header names / values in each event callback request.
events_callback_parameters no A json object whose attribute names and values will be sent as request attribute names and values in each event callback request.
allowed_ip_addresses no A json array with the list of valid IP addresses and/or subnetworks in CIDR notation. If not specified the current addresses remain. If you want to eliminate the restriction specify the 0.0.0.0/0 subnet.

Trigger Call method

Use this request to trigger a call from your CRM, ERP or any other enterprise systems. Call triggering works as follows. Firts you use the call trigger method to tell VozTelecom which extension you want to dial to which destination. The destination can be another extension or a geographical number, fixed, mobile, national or international. Any number that you could dial from your phone is a valid number. You don't have to worry about the dial out prefix, if your PBX uses a dialout out prefix (for instance 0) the API will add it automatically in case it is not present.

When you make a call triggering request you can specify some data related to your application that you want back in your request. Every event generated by the call triggered by your request will include the data you specified allowing you to correlate request and events. The data can be sent back to your system as a set of headers and/or parameters.

HTTP Request

POST https://config.work.oigaa.com/vtcrm/api/call

curl "https://config.work.oigaa.com/vtcrm/api/call"
  -H "Authorization: VTCRM-Basic 83isocjid5hyd02sdjiembslw323"

The above command takes a JSON payload structured like this:

  {
    "extension": "203",
    "destination": "647460197",
    "request_callback_headers": {
      "X-Request-Header" : "A request header value",    
      "X-Another-Request-Header" : "Another request header value"    
    },
    "request_callback_parameters": {
      "a_request_parameter" : "A request parameter value",    
      "another_request_parameter" : "Another request parameter value" 
    }
  }

Query Parameters

Parameter Mandatory Description
extension yes The extension that will perform the call
destination yes The destination number of the call
request_callback_headers no A json object whose attribute names/values will be sent as header names / values in each event callback request of the call triggered
request_callback_parameters no A json object whose attribute names and values will be sent as request attribute names and values in each event callback request of the call triggered

Drop Call method

Use this request to drop an ongoing call from your CRM. You have to send the id of the call that you want to drop. The callId is one of the attributes in the events API and it is present in all of the events related to the call.

HTTP Request

POST https://config.work.oigaa.com/vtcrm/api/drop

curl "https://config.work.oigaa.com/vtcrm/api/call"
  -H "Authorization: VTCRM-Basic 83isocjid5hyd02sdjiembslw323"

The above command takes a JSON payload structured like this:

  {
    "callId": "471900"
  }

Query Parameters

Parameter Mandatory Description
callId yes The id of the call as per the event API.

Redirect Call method

Use this method to make a cold transfer of an established call to another extension. You have to send the id of the call leg that you want to redirect. A call can have one or more call legs depending on the path taken inside the PBX. A call leg represents a specific segment of a call. A good example would be a call delivered to a group of extensions that ring simultaneously. Each extension ringing will generate events with its own callLegId. The callLegId is present at every event generated by the Events API.

HTTP Request

POST https://config.work.oigaa.com/vtcrm/api/redirect

curl "https://config.work.oigaa.com/vtcrm/api/call"
  -H "Authorization: VTCRM-Basic 83isocjid5hyd02sdjiembslw323"

The above command takes a JSON payload structured like this:

  {
    "callLegId": "1542399572160.-703374",
    "destination" : "202"
  }

Query Parameters

Parameter Mandatory Description
callLegId no The id of the call leg that you want to redirect. If you don't send a callLegId the callId will be used if possible.
destination yes The destination number where you want the call to be transferred.

Events API

Events inform your CRM system of what's going on in the network. Every incoming or outgoing call in your PBX will trigger one or more events that will allow you to keep your information systems synchronized in realtime time with your communications. It is worth noting that all event generation and notificacion takes place on the cloud and don't rely on your fixed and mobile phones being powered on or connected. If you need to open up your firewalls to receive events from VozTelecom the source IP address will be one in the subnet 193.22.119.0/24.

Events are generated on a per-extension basis. That means means that when you receive an incoming call from an external number to the extension 203 for instance, you will receive a series of events related to such call, that will inform you of an incoming call whose destination is the extension 203. When the extension let's say, 202, performs an outgoing call to an external destination you will receive a series of events reporting an outgoing call with the extension 202 as source. When the extension 202 calls the extension 203 you will receive two series of events describing the same call from two points of view. From the point of view of extension 203 where call is incoming, and from the point of view of extension 202 where the call is outgoing.

Events Callbacks

When you use the request API to configure how you want to receive the communication events you specify a callback URL as well as a set of headers and parameters. All parameters and headers that you specified will be present in each and every event notification request. They will be exactly the same across all requests unless you change them with a call the API configuration method.

Event callback notification

The events will be reported in order of arrival one by one. Every request will contain a X-VTCRM-PBXID header indicating to which PBX the event belongs to

POST https://callbackserver.yourdomain.com/vtcrm/callback

X-VTCRM-PBXID: yourPBXId

> Event data comes in the form of a JSON object with every notification

{
    "callId":"321296",
    "callLegId":"1541763052549.-478323",
    "displayedExternalNumber":"+34647460197",
    "displayedLabel":"647460197",
    "displayedNumber":"0647460197",
    "isIncoming":true,
    "isRecording":false,
    "eventTimestamp":"1541763052569",
    "state":"ringing",
    "stateCause":"causeNormal",
    "extension":"203"
}

Event Attributes

Parameter Always Present Description
callId yes The id of the call
callLegId yes The id of the call leg. A call can have various legs when there is a transfer, an parallel delivery, etc...
isIncoming yes Indicates wether the call is incoming or outgoing
displayedExternalNumber yes The long number of the entity being called for an outgoing call or calling in for incoming calls.
displayedLabel yes The label of the entity being called for an outgoing call or calling in for incoming calls.
displayedNumber yes The number of the entity being called for an outgoing call or calling in for incoming calls.
isRecording yes Indicates wether this call is being recorded or not
eventTimestamp yes The timestamp at which this event was created
state yes Status of the call leg
stateCause yes Reason for the call leg to be in this state
extension yes The extension that sends or receives the call

Incoming answered call example

The following example depicts the events generated related to the reception of an incoming call from the number 647460197 to the extension 203

> Incoming call from 647460197, the extension 203 rings.
{
   "callId":"471900",
   "callLegId":"1542399572160.-703374",
   "displayedExternalNumber":"+34647460197",
   "displayedLabel":"647460197",
   "displayedNumber":"0647460197",
   "isIncoming":true,
   "isRecording":false,
   "eventTimestamp":"1542399572176",
   "state":"ringing",
   "stateCause":"causeNormal",
   "extension":"203"
}

> The extension answers the call. The state changes from ringing to talking. 

{
   "callId":"471900",
   "callLegId":"1542399572160.-703374",
   "displayedExternalNumber":"+34647460197",
   "displayedLabel":"647460197",
   "displayedNumber":"0647460197",
   "isIncoming":true,
   "isRecording":false,
   "eventTimestamp":"1542399578197",
   "state":"talking",
   "stateCause":"causeNormal",
   "extension":"203"
}

> The extension drops the call. The state changes from talking to dropped. 

{
   "callId":"471900",
   "callLegId":"1542399572160.-703374",
   "displayedExternalNumber":"+34647460197",
   "displayedLabel":"647460197",
   "displayedNumber":"0647460197",
   "isIncoming":true,
   "isRecording":false,
   "eventTimestamp":"1542399582021",
   "state":"dropped",
   "stateCause":"causeNormal",
   "extension":"203"
}

Incoming missed call example

The following example depicts the events generated related to the reception of an incoming call from the number 647460197 to the extension 203 that is never answered


> Incoming call from 647460197, the extension 203 rings.

{
   "callId":"472362",
   "callLegId":"1542401480524.-704062",
   "displayedExternalNumber":"+34647460197",
   "displayedLabel":"647460197",
   "displayedNumber":"0647460197",
   "isIncoming":true,
   "isRecording":false,
   "eventTimestamp":"1542401480534",
   "state":"ringing",
   "stateCause":"causeNormal",
   "extension":"203"
}


> After receiving no answer the caller drops the call. The state changes directly from ringing to dropped.

{
   "callId":"472362",
   "callLegId":"1542401480524.-704062",
   "displayedExternalNumber":"+34647460197",
   "displayedLabel":"647460197",
   "displayedNumber":"0647460197",
   "isIncoming":true,
   "isRecording":false,
   "lastModificationTime":"1542401484054",
   "state":"dropped",
   "stateCause":"causeNormal",
   "extension":"203"
}   

Outgoing answered call

The following example depicts the events generated related to the emission of an outgoing call to the number 647460197 from the extension 203 that is answered


> Outgoing call to 647460197, the external number rings 

{
   "callId":"472367",
   "callLegId":"1542401510978.-704065",
   "displayedExternalNumber":"+34647460197",
   "displayedLabel":"647460197",
   "displayedNumber":"0647460197",
   "isIncoming":false,
   "isRecording":false,
   "eventTimestamp":"1542401510992",
   "state":"alerting",
   "stateCause":"causeNormal",
   "extension":"203"
}

> 647460197 answers the call

{
   "callId":"472367",
   "callLegId":"1542401510978.-704065",
   "displayedExternalNumber":"+34647460197",
   "displayedLabel":"647460197",
   "displayedNumber":"0647460197",
   "isIncoming":false,
   "isRecording":false,
   "eventTimestamp":"1542401516677",
   "state":"talking",
   "stateCause":"causeNormal",
   "extension":"203"
}

The call is dropped

{
   "callId":"472367",
   "callLegId":"1542401510978.-704065",
   "displayedExternalNumber":"+34647460197",
   "displayedLabel":"647460197",
   "displayedNumber":"0647460197",
   "isIncoming":false,
   "isRecording":false,
   "eventTimestamp":"1542401521090",
   "state":"dropped",
   "stateCause":"causeNormal",
   "extension":"203"
}


Outgoing unanswered call

The following example depicts the events generated related to the emission of an outgoing call to the number 647460197 from the extension 203 that is not answered


> Outgoing call to 647460197, the external number rings

{
   "callId":"472388",
   "callLegId":"1542401535786.-704094",
   "displayedExternalNumber":"+340647460197",
   "displayedLabel":"0647460197",
   "displayedNumber":"00647460197",
   "isIncoming":false,
   "isRecording":false,
   "eventTimestamp":"1542401535788",
   "state":"alerting",
   "stateCause":"causeNormal",
   "extension":"203"
}

> After receiving no answer the extension 203 drops the call. The state changes directly from ringing to dropped.
{
   "callId":"472388",
   "callLegId":"1542401535786.-704094",
   "displayedExternalNumber":"+340647460197",
   "displayedLabel":"0647460197",
   "displayedNumber":"00647460197",
   "isIncoming":false,
   "isRecording":false,
   "eventTimestamp":"1542401541347",
   "lineId":"-704094",
   "state":"dropped",
   "stateCause":"causeNormal",
   "extension":"203"
}

Call Recording

Call recording can be activated on a per extension basis or generally for all the PBX depending on your product. A few minutes after a recorded call finishes the system will notify of its availability by means of an special event with the state "recordingAvailable". The actual exchange of the recordings (normally mp3 files) between VozTelecom and your systems is out of the scope of this API and will by agreed with each partner. It is worth noting though that the "recordingAvailable" event can be subject to the actual completion of the transfer so your application can safely count on the media being available to the users after the reception of the notification.


> Notification of the availability of a call recording
{
   "callId":"472388",
   "state":"recordingAvailable",
   "stateCause":"informative"
} 

Security

All requests to the API have to be authenticated with an Authorization Header. The authorization header contains the API key that identifies your communications service in VozTelecom and allows you to use it via this API. It is very important that you keep this key private and never share it with anyone. All requests that use the API key are sent over HTTPS thus avoiding the possibility of sniffing it out.

If you want to further secure your service you can specify a list of IP addresses/networks that you consider valid origins for the API requests made with your key. If a request from an unauthorized IP arrives it will be automatically declined regardless the fact that the key is valid. When we setup your account we will ask you for an initial list of IP addresses that you want to white list. After that you can manage the list using the API configuration method.

Regarding the event notifcations that you will receive from VozTelecom, if you need to do firewall arrangements the origin address of the requests will always be in the subnet 193.22.119.0/24. This network is owned and operated exclusively by VozTelecom. Last but not least we strongly recommend that you provide an HTTPS endpoint for event notification but you are entitled to use HTTP if you can't. Please keep in mind that the policy may change in the future so please consider setting up encryption as long as that is possible.

Errors

Standar HTTP errors are used in all the requests methods. The reason for the error can be clarified beyond the status code in the Reason Phrase

Error Code Meaning
400 Bad Request -- Your request is invalid. Check the reason phrase to know what is wrong.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- You are not allowed to carry out the action requested.
405 Method Not Allowed -- You used a method other than POST to access the API
429 Too Many Requests -- You're requesting too often. 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.