Authentication & Headers
Before you try sending any requests to the API, generate an API key. You can do that in your account settings after logging in to LiveCall. In the following examples we'll use a fake key: change-to-your-api-key.
To authenticate any requests made to our API, you must include an authorization header. Also remember about a correct JSON Content-Type header. So each of your requests must have the following headers:
Authorization: Token token=change-to-your-api-key
Content-Type: application/json


Calls

Making calls

Making calls using LiveCall.io API is as simple as making a POST request to /calls endpoint. There are just two attributes needed to make a call:
filter_id — an ID of the target group (go to https://app.livecall.io/targeting edit target group and in the url https://app.livecall.io/targeting/filter_id/edit you'll find your filter_id),
phone_number — the phone number of your customer.

And two optional:
scheduled_for — a ISO8601 timestamp a planned time in which the call should be executed; note that this timestamp is time zone sensitive, just conform to the ISO8601 notation,
user_id — an ID of a user (go to https://app.livecall.io/users edit user and in the url https://app.livecall.io/users/user_id/edit you'll find your user_id) if you wish to specifically select one user; if you leave this empty, an available user will be picked up from the target group you specified via filter_id attribute; you can select a user even if they're not assigned to the specified target group.

An example request could look like this:
POST https://api.livecall.io/v1/calls
Authorization: Token token=change-to-your-api-key
Content-Type: application/json

{
"call": {
"filter_id": "43321",
"phone_number": "+1 (222) 222 2222",
"scheduled_for" ""2017-04-28T12:00:00Z"
}
}


And for such a request, you'll receive a response like this:
{
"call": {
"id": "id-of-the-new-call",
"filter_id": "43321",
"user_id": "123",
"phone_number": "+1 (222) 222 2222",
"scheduled_for": "2017-04-28T12:00:00Z"
}
}

Et voilà!

Checking call status

To check status of an existing call, make a GET request to /calls/:call_id endpoint. Like this:

GET https://api.livecall.io/v1/calls/123
Authorization: Token token=change-to-your-api-key
Content-Type: application/json


which will return a response like this:

{
"call": {
"id": 123,
"outcome": "successful",
"status": "ended",
"user_id": 456,
"filter_id": 789,
"phone_number": "+44 123123123",
"scheduled_for": null,
"created_at": "2017-07-17T14:43:38.586+02:00",
"initiated_at": "2017-07-17T14:43:41.510+02:00",
"started_at": "2017-07-17T14:44:01.878+02:00",
"ended_at": "2017-07-17T14:44:15.406+02:00",
"duration": 13.528892,
"custom_fields_data": {
"first_name: "Mary",
"email": "mary@example.com"
}
}
}


Recordings

For calls that have been recorded, you can download the recordings. To do this first request a download link:

GET https://api.livecall.io/v1/calls/123/recording
Authorization: Token token=change-to-your-api-key
Content-Type: application/json


This will return a recording object:

{
"recording": {
"id": 123,
"call_id": 123,
"url": "https://dl.livecall.io/downloads/recordings/123?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJnaWQ6Ly9saXZlY2FsbC9SZWNvcmRpbmcvMTkwMyIsImV4cCI6MTU0MzkyMjI0NH0.lGe9GizLZb2cQvXtwr0axVls2r-ra7I0f-vww50dmO"
}
}


The url property contains a unique, temporary URL to the recording file. You should use it immediately as it's only valid for a short period of time.

Webhooks

To get notified when a call is created or ends, subscribe on of our webhooks. You can do that via our dashboard: https://app.livecall.io/settings/integrations/webhooks.

Checking availability
You might want to check if any of your consultants are available before even offering a callback to your users. In order to do that, just query an appropriate filter:
GET https://api.livecall.io/v1/filters/change-to-id-of-the-segment
Authorization: Token token=change-to-your-api-key
Content-Type: application/json


The response will look something like that:
{
"filter": {
"id": "id-of-the-segment",
"status": "available",
"available_call_times":["2017-04-03T11:00:00Z", "2017-04-03T11:30:00Z"]
}
}


The status attribute will be either `available`— when any of the consultants' working hours covers the present time, or unavailable — when it doesn't.

Managing users

Listing all users

Requesting users like this:

GET https://api.livecall.io/v1/users
Authorization: Token token=change-to-your-api-key
Content-Type: application/json


will return a list of all users on your account. Like this:

{
"users": [{
"id": 123,
"name": "Andrew",
"phone_number": "+48 123123123"
}, {
"id": 124,
"name": "Matt",
"phone_number": "+48 456456456"
}]
}


Creating a user

To create a user, make a POST request to /users endpoint.

You must provide two self-explanatory arguments:
name,
phone_number.

Example:

POST https://api.livecall.io/v1/users
Authorization: Token token=change-to-your-api-key
Content-Type: application/json

{
"user": {
"name": "Beata",
"phone_number": "+1 (222) 222 2222"
}
}


As a response, you'll get an user object:

{
"user": {
"id": "id-of-the-new-user",
"name": "Beata",
"phone_number": "+1 2222222222"
}
}


Updating a user

To update a user, make a PATCH request to /users/id-of-user endpoint formatting the request the same way as you would when creating a user (see previous section).

Removing a user

To remove a user, make a DELETE request to /users/id-of-user endpoint.
Was this article helpful?
Cancel
Thank you!