API

Verboice API

Libraries

There are some libraries for accessing this API in several languages:

• Ruby: https://bitbucket.org/instedd/verboice-api-ruby
• R: https://bitbucket.org/instedd/rverboice

Authentication

Authentication is always http://en.wikipedia.org/wiki/Basic_access_authentication with the account email as the username and the account password as the password.

Enqueue Call

This action enqueues a call in Verboice.

HTTP GET /api/call?channel=<channel>&address=<address>

or

HTTP POST /api/call

Required parameters

• channel: the name of the channel in which to enqueue the call
• address: the phone number or sip address to call

Specifying a call flow to execute

These are the different ways to specify a call flow to execute:

• Specify a call_flow_id parameter with the id of a call flow
• Speficy a call_flow parameter with the name of a call flow
• Speficy the flow in the POST data as, for example, a http://www.twilio.com/docs/api/twiml. In this case the project will be the one associated to the channel specified with the channel parameter, or can be overwritten by specifying a project_id parameter with the id of a project.

Specifying call variables

These can be specified with query parameters. For example, to define an "age" variable with value 38, you can do:

HTTP GET /api/call?channel=<channel>&address=<address>&vars[age]=38

Optional time-related parameters

• schedule_id or schedule to specify the schedule to use with and id or name, respectively
• not_before to specify that the call must not be issued before a date (for example: '2012-01-02 10:11:12')
• not_after to specify that the call must not be issued after a date (for example: '2012-01-02 10:11:12')
• time_zone to specify a time zone for the previous parameter (for example: 'Buenos Aires')

Get info on a call

HTTP GET /api/calls/<call_ID>/details.json

Returns the following fields in a JSON object, new on 3.0:

call_id
state
project_id
project_name
started_at
finished_at
not_before
direction
channel_id
channel_name
call_flow_id
call_flow_name
contact_id
contact_address
schedule_id
schedule_name
fail_reason
fail_code
fail_details

Get all contacts in a project

HTTP GET /api/projects/<project_id>/contacts.json

Example response:

[
  {
    id: 1,
    addresses: ["1543949458", "1543949459"],
    vars: {age: 38, "favorite color": "blue"}
  },
  {
    id: 2,
    addresses: ["1556948544"],
    vars: {age: 42}
  },
]

Get a contact in a project given an address

HTTP GET /api/projects/<project_id>/contacts/by_address/<address>.json

Example request:

HTTP GET /api/projects/<project_id>/contacts/by_address/1543949458.json

Example response:

{
  id: 1,
  addresses: ["1543949458", "1543949459"],
  vars: {age: 38, "favorite color": "blue"}
}

Update a contact's variable in a project given an address

HTTP PUT /api/projects/<project_id>/contacts/by_address/<address>.json?vars[var_name]=var_value

The PUT body must be empty, but must still be specified (with length 0). The response is the updated contact, as a JSON.

Example request:

HTTP PUT /api/projects/<project_id>/contacts/by_address/1543949458.json?vars[age]=39

Example response:

{
  id: 1,
  addresses: ["1543949458", "1543949459"],
  vars: {age: 39, "favorite color": "blue"}
}

Update all contacts' variables in a project given an address

HTTP PUT /api/projects/<project_id>/contacts/all.json?vars[var_name]=var_value

The PUT body must be empty, but must still be specified (with length 0). The response is the updated contacts, as a JSON.

Example request:

HTTP PUT /api/projects/<project_id>/contacts/all.json?vars[age]=39

Example response:

[
  {
    id: 1,
    addresses: ["1543949458", "1543949459"],
    vars: {age: 39, "favorite color": "blue"}
  },
  {
    id: 2,
    addresses: ["1556948544"],
    vars: {age: 39}
  },
]