NAV Navbar
shell
  • Introduction
  • Authentication
  • Webhook subscriptions API
  • Webhooks
  • Telephony events API
  • Click-to-call API
  • Errors
  • Introduction

    Welcome to the Voverc API reference! You can use our API key to access Voverc API endpoints, if you still don't have one, generate it in the Voverc Control Panel dedicated area API key

    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.voverc.com/api/v1/some_call" -H "Voverc-Auth: your_api_key"
    

    Voverc-Auth: your_api_key

    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 Voverc, 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.voverc.com/api/v1/webhook-subscriptions

    This request setups a notification on endpoint http://my_endpoint.domain when CALL_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"}'
    "https://developer.voverc.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"
    }
    

    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, PHONE_CALL, VOICE_MAIL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP

    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, PHONE_CALL, VOICE_MAIL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP
    failed_count Number of failed attempts
    last_error Last occurred error

    Update a webhook subscription

    This endpoint updates an existing webhook subscription

    HTTP Request

    PUT https://developer.voverc.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.voverc.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"
    }
    

    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, PHONE_CALL, VOICE_MAIL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP
    enabled false Boolean to enable / disable subscription

    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, PHONE_CALL, VOICE_MAIL, 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

    Get webhook subscriptions

    This endpoint returns all the existing webhook subscriptions

    HTTP Request

    GET https://developer.voverc.com/api/v1/webhook-subscriptions

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voverc.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"
      },
      {
        "id": "f98b8c5d-4935-4e32-b6e4-490687c7f14d",
        "type": "CALL_ANSWERED",
        "failed_count": 0,
        "enabled": true,
        "callback_url": "http://my_endpoint.domain"
      },
      {
        "id": "9cf8e5e7-d32a-4fc9-bc4a-1c2c9f2aa82d",
        "type": "CALL_HANGUP",
        "failed_count": 0,
        "enabled": true,
        "callback_url": "http://my_endpoint.domain"
      }
    ]
    

    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, PHONE_CALL, VOICE_MAIL, 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

    Get call webhook subscription

    This endpoint returns an existing webhook subscription

    HTTP Request

    GET https://developer.voverc.com/api/v1/webhook-subscriptions/${id}

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voverc.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"
    }
    

    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, PHONE_CALL, VOICE_MAIL, 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

    Delete a webhook subscription

    This endpoint removes an existing webhook subscription

    HTTP Request

    DELETE https://developer.voverc.com/api/v1/webhook-subscriptions/${id}

    curl -X DELETE -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voverc.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 Voverc. 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",
        "sipUsername": "sip_138oksfg",
        "userEmail": "email@domain.com",
        "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:

    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
    userEmail string Email address of the user subject of the event
    userExtension number Extension of the user subject of the event
    sipUsername string SIP username 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",
        "userEmail" : "email@domain.com",
        "userExtension" : 101,
        "sipUsername" : "sip_user"
    }
    

    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

    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
    type string Can be one of the following values: PHONE_CALL, FAX_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
    archived boolean True if this event has been marked as archived
    recorded boolean True if this phone call has an associated call recording

    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",
        "lastEvent": "CALL_TERMINATED",
        "duration": 4,
        "archived": false,
        "callId": "1734bfbbd5dc4a9c8de1d2e5235e6389",
        "recorded": false
    }
    

    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"
    }
    

    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.voverc.com/api/v1/telephony-events

    This request fetches all events related to number 06123456789, between dates 2018-03-11T07:00:00 and 2018-04-16T07:00:00

    curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    -d '{"date_time_from":"2018-03-11T07:00:00","date_time_to":"2018-04-16T07:00:00", "number":"06123456789"}'
    "https://developer.voverc.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
            }
      ],
        "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
    date_time_from false Temporal interval start in ISO8601 format
    date_time_to false Temporal interval end in ISO8601 format

    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.voverc.com/api/v1/telephony-events/${id}

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voverc.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.voverc.com/api/v1/telephony-events?callId=${callId}

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
    "https://developer.voverc.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.

    Create a click-to-call

    This endpoint creates a click-to-call resource

    HTTP Request

    POST https://developer.voverc.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":"ctc_support","extension":"101","outboundNumber":"+39123456789","dial_first":"contact"}'
    "https://developer.voverc.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.voverc.com/api/v1/click-to-call/${id}

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voverc.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.voverc.com/api/v1/click-to-call

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voverc.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.voverc.com/api/v1/click-to-call/${id}

    curl -X DELETE -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voverc.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.voverc.com/api/v1/click-to-call/${id}/connect

    This request connects with a phone call contact +39123456789 and extension 101

    curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    -d '{"contact":"+39987654321"}'
    "https://developer.voverc.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 Voverc 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.