Calls

This section describes /calls REST resource, enabaling developers to retrive call logs, make calls and hangup calls.

GET /calls

Call Records Filtering

Name Type Description
direction string Only show calls that are either inbound or outbound
to string Only show calls to this phone number
status string

Filter calls based on status, available options are:

  • completed
  • busy
  • no-answer
  • canceled
started_at date

Filter calls based on the date and time they were started.

started_at only accepts ISO 8601 format.

You may use inequalities (>= or <=) to filter calls or use .. (two donts) as a range, examples would be:

  • started_at<=2012-04-01T00:01:01Z
  • started_at>=2012-04-01T00:02:02Z
  • started_at=2012-04-01T00:03:03Z..2012-04-01T00:04:04Z

Example Request

curl "https://api.xbp.io/calls" -u API_KEY:

Sample Response

{
  "calls": [
    {
      "uuid": "c4e00288-cbcd-4234-a7ce-a78994f7aeff",
      "url": "/calls/c4e00288-cbcd-4234-a7ce-a78994f7aeff",
      "from": {
        "type": "Phone",
        "number": "+18885551234",
        "caller_name": "Awesome Caller"
      },
      "to": {
        "type": "Person",
        "id": 1,
        "url": "/people/36"
      },
      "started_at": "2012-04-02T15:52:10Z",
      "ended_at": "2012-04-02T15:52:27Z",
      "direction": "inbound",
      "status": "no-answer",
      "via_phone_number": {
        "number": "+14085551234",
        "url": "/phone_numbers/+14085551234"
      },
      "duration": 17,
      "voicemail": {
        "id": 99999,
        "duration": 5,
        "url": "/voicemails/99999"
      }
    },...
  ],
  "pagination": {
    "current_page": 1,
    "next_page": 2,
    "per_page": 50,
    "page_size": 50,
    "total_pages": 2,
    "total_records": 51
  }
}

Call Logs Properties

Name Description
uuid The uuid of the call
url The url to retrive call information
from

JSON object representing the source of the call.

If the type is Phone it means call was made from a phone (cell or landline)

JSON fields:

  • type the type of source of the call
  • number if the type is Phone, the number fields contains the phone number that called.
  • idany type other than Phone will have an id associated to it pointing to a local XBP resource.
  • urlany type other than Phone will have a url associated to it pointing to a local XBP resource.

to

JSON object representing the destination of the call.

If the type is Phone it means call was made from a phone (cell or landline)

JSON fields:

  • type the type of source of the call
  • number if the type is Phone, the number fields contains the phone number that called.
  • idany type other than Phone will have an id associated to it pointing to a local XBP resource.
  • urlany type other than Phone will have a url associated to it pointing to a local XBP resource.

started_at

The date and time call was started in ISO 8601 format.

ended_at

The date and time call was ended in ISO 8601 format.

direction The direction of call, indicates wether the call was inbound or outbound
status The status of the call:
  • completed call was answered
  • busy line was busy
  • no-answer missed call
  • canceled caller hungup the phone before being answered
via_phone_number JSON object representing the inbound phone number that received the call. The number fields contains the number that was called.
duration Duration of the call in seconds
voicemail If the call was ended up in a voicemail inbox, this object holds information about the voicemail that was left.
updated_at The date that this resource was updated in ISO 8601 format.

Example 1: Filter all inbound calls

curl https://api.xbp.io/calls?direction=inbound -u API_KEY:

Example 2: Filter all missed calls

curl https://api.xbp.io/calls?status=no-answer -u API_KEY:

Example 3: Filter all missed calls

curl https://api.xbp.io/calls?status=no-answer -u API_KEY:

Example 4: Filter all calls made to an inbound phone number

curl https://api.xbp.io/calls?to=+18885551234 -u API_KEY:

Example 5: Filter all calls before April Fool's Day

curl https://api.xbp.io/calls?started_at<=2012-04-01T00:00:00Z -u API_KEY:

Example 6: Filter all calls after April Fool's Day

curl https://api.xbp.io/calls?started_at>=2012-04-01T00:00:00Z -u API_KEY:

Example 7: Filter all calls in a date range

curl https://api.xbp.io/calls?started_at=2012-04-01T00:00:00Z..2012-05-01T00:00:00Z \
     -u API_KEY:

Example 8: Using multiple filters

curl -X GET https://api.xbp.io/calls                      \
     -u API_KEY:                                                \
     -d started_at="2012-04-01T00:00:00Z..2012-05-01T00:00:00Z" \
     -d status="no-answer"                                      \
     -d direction="inbound"

POST /calls

Making Call Request Parameters

Name Type Description
from string The originating local XBP extension or a phone number
to string Can be any of the defined extensions in your PBX or phone number. If you send a 7 digits phone number, we will use the defined area code from your SIP account as the area code.

Optional Parameters

display_name string When display name is set, the originator will see that name on the screen of his phone. For instance it can be helpful to have the name of the person you going to call to on the screen on your phone.
display_number string Same as display_name, the display number will be used as the Caller ID showing on the originated phone. Please note that display_name and display_number are not your Caller ID that the callee will see, this is only on your phone. The callee's Caller ID is automatically set from the extension's defined Caller ID.

Example Request

curl -X POST https://api.xbp.io/calls \
     -u API_KEY:                            \
     -d from=110                            \
     -d to=18885551234                      \
     -d display_number=14085558899          \
     -d display_name="Awesome Caller"

Sample Response

{
  "call_uuid": "c27853a7-0d34-447e-8c26-e4e046d9be1e",
  "message": "Call originated"
}

DELETE /calls/{call_uuid}

Call Hangup Request

No parameter is needed, only the uuid of the call should be supllied in /calls resource.

Example Request

curl -X DELETE https://api.xbp.io/v1/calls/c27853a7-0d34-447e-8c26-e4e046d9be1e \
     -u API_KEY:

Sample Response

{
  "call_uuid": "c27853a7-0d34-447e-8c26-e4e046d9be1e",
  "message": "Call hungup"
}