Introduction

Welcome to the phone callback API! You can use our API to :

Callback Requests :

Get callback requests with or without filters
Create a callback request (instant or scheduled callback)
Get a single callback request

Brands :

Get brands with or without filters, with every associated ressources (category and schedule)
Get a single brand, with every associated ressources (category and schedule)

The API is using jsonapi.org specification. There is clients availables for many languages. Our implementation is simple, so you may not need to use a client, but it strongly recommanded to use one, it should be easier for you.

We have language bindings in Shell and Ruby! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

We will show you how to write the corresponding code in pure Ruby and with the gem json_api_client

Prerequisites

To start using this API, you'll need an authentification token. Ask a manager or a developer to create one for you. We can provide a token for test/staging purposes and another for a production environnement, tell us which one you want.

We need the name and a short description of your application to create a token.

Endpoint

Each callback website can answers to your API requests without any scoping.

It means you have access to the same resources on any websites.

The common endpoint path is /api/v1/.

So for example, the URL is https://rappel.selectra.info/api/v1/ where rappel.selectra.info can change for the domain of your choice. The only things that change between your requests on each domains, are the errors messages. If the translation is available, your errors messages will be translated in the website language.

Pagination

Here's what we are using for pagination : jsonapi.org pagination specifications

We return every resources to a request without any pagination parameters
Paginations links are available when it makes sense (self, first, prev, next & last)
page[number] and page[size] parameters are allowed to paginate any resource

Filtering

jsonapi.org filtering specifications

When available, the filter parameter can be use to filter resources you are retrieving.

More informations in each resources sections.

Authentication

# Using URL parameter
curl "https://rappel.selectra.info/api/v1/brands?token=YOUR_API_KEY"

# Using request header
curl "https://rappel.selectra.info/api/v1/brands" \
  -H "X-Api-Key: YOUR_API_KEY"

require 'faraday'

# Using URL parameter
Faraday.get "https://rappel.selectra.info/api/v1/brands?token=YOUR_API_KEY"

# Using request header
conn = Faraday.new(url: 'https://rappel.selectra.info')
conn.get do |req|
  req.url '/api/v1/brands'
  req.headers['X-Api-Key'] = 'YOUR_API_KEY'
end

require 'json_api_client'

# Using URL parameter
module PhoneCallbackAPI
  module V1
    class Base < JsonApiClient::Resource
      self.site = 'https://rappel.selectra.info/api/v1/?token=YOUR_API_KEY'
    end

    class Brand < Base
    end
  end
end

# Using request header
module PhoneCallbackAPI
  module V1
    class Base < JsonApiClient::Resource
      self.site = 'https://rappel.selectra.info/api/v1/'
      self.connection_options = { headers: { 'X-Api-Key' => 'YOUR_API_KEY' } }
    end
  end
end

The authentification is made by passing a token to each request. You can pass it as an URL parameter or in a header :

Header name : X-Api-Key: YOUR_API_KEY
HTTP parameter : ?token=YOUR_API_KEY

Brands

All Brands

curl "https://rappel.selectra.info/api/v1/brands"

require 'faraday'

Faraday.get "https://rappel.selectra.info/api/v1/brands"

require 'json_api_client'

module PhoneCallbackAPI
  module V1
    class Base < JsonApiClient::Resource
      self.site = 'https://rappel.selectra.info/api/v1/'
    end

    class Brand < Base
    end

    class Category < Base
    end

    class Schedule < Base
    end

    class Website < Base
    end
  end
end

PhoneCallbackAPI::V1::Brand.all

This endpoint retrieves all brands, including associated models :

Website
Category

Filtering

curl -G \
    --data-urlencode "filter[name_param]=direct-energie" \
    https://rappel.selectra.info/api/v1/brands

curl -G \
    --data-urlencode "filter[number]=+33923456789" \
    https://rappel.selectra.info/api/v1/brands

require 'faraday'

Faraday.get "https://rappel.selectra.info/api/v1/brands?filter[name_param]=direct-energie"
Faraday.get "https://rappel.selectra.info/api/v1/brands?filter[number]=+33923456789"

require 'json_api_client'

module PhoneCallbackAPI
  module V1
    class Base < JsonApiClient::Resource
      self.site = 'https://rappel.selectra.info/api/v1/'
    end

    class Brand < Base
    end

    class Category < Base
    end

    class Schedule < Base
    end

    class Website < Base
    end
  end
end

PhoneCallbackAPI::V1::Brand.where(name_param: 'direct-energie').all
PhoneCallbackAPI::V1::Brand.where(number: '+33923456789').all

You can use these filters :

name
name_param
number (E.164 format)
callback_type (talkdesk, new_voice_media, twilio, etc...)

Retrieve a Brand

curl "https://rappel.selectra.info/api/v1/brands/1"

require 'faraday'

Faraday.get "https://rappel.selectra.info/api/v1/brands/1"

require 'json_api_client'

module PhoneCallbackAPI
  module V1
    class Base < JsonApiClient::Resource
      self.site = 'https://rappel.selectra.info/api/v1/'
    end

    class Brand < Base
    end

    class Category < Base
    end

    class Schedule < Base
    end

    class Website < Base
    end
  end
end

PhoneCallbackAPI::V1::Brand.find(1)

This endpoint retrieves one brand, including associated models :

Website
Category
Schedule

Callback Requests

All Callback Requests

curl "https://rappel.selectra.info/api/v1/callback_requests"

require 'faraday'

Faraday.get "https://rappel.selectra.info/api/v1/callback_requests"

require 'json_api_client'

module PhoneCallbackAPI
  module V1
    class Base < JsonApiClient::Resource
      self.site = 'https://rappel.selectra.info/api/v1/'
    end

    class CallbackRequest < Base
    end
  end
end

PhoneCallbackAPI::V1::CallbackRequest.all

This endpoint retrieves all callback requests.

Filtering

curl -G \
    --data-urlencode "filter[phone]=+33123456789" \
    https://rappel.selectra.info/api/v1/callback_requests

curl -G \
    --data-urlencode "filter[brand]=1" \
    https://rappel.selectra.info/api/v1/callback_requests

require 'faraday'

Faraday.get "https://rappel.selectra.info/api/v1/callback_requests?filter[phone]=+33123456789"
Faraday.get "https://rappel.selectra.info/api/v1/callback_requests?filter[brand]=1"

require 'json_api_client'

module PhoneCallbackAPI
  module V1
    class Base < JsonApiClient::Resource
      self.site = 'https://rappel.selectra.info/api/v1/'
    end

    class CallbackRequest < Base
    end
  end
end

PhoneCallbackAPI::V1::CallbackRequest.where(phone: '+33123456789').all
PhoneCallbackAPI::V1::CallbackRequest.where(brand: '1').all

You can use these filters :

phone
brand
ip_address
user_agent

Retrieve a Callback Request

curl "https://rappel.selectra.info/api/v1/callback_requests/9fb5ca71-1501-4b6a-9f12-e1f1d4a8eadc"

require 'faraday'

Faraday.get "https://rappel.selectra.info/api/v1/callback_requests/9fb5ca71-1501-4b6a-9f12-e1f1d4a8eadc"

require 'json_api_client'

module PhoneCallbackAPI
  module V1
    class Base < JsonApiClient::Resource
      self.site = 'https://rappel.selectra.info/api/v1/'
    end

    class CallbackRequest < Base
    end
  end
end

PhoneCallbackAPI::V1::CallbackRequest.find('9fb5ca71-1501-4b6a-9f12-e1f1d4a8eadc')

This endpoint retrieves one callback request.

Create a Callback Request

curl -X POST \
  https://rappel.selectra.info/api/v1/callback_requests/ \
  -F 'data[attributes][phone]=+33123456788' \
  -F 'data[attributes][brand_id]=1'

require 'faraday'

params = { data: { attributes: { phone: '+33123456788', brand_id: 1 } } }
Faraday.post "https://rappel.selectra.info/api/v1/callback_requests/", params

require 'json_api_client'

module PhoneCallbackAPI
  module V1
    class Base < JsonApiClient::Resource
      self.site = 'https://rappel.selectra.info/api/v1/'
    end

    class CallbackRequest < Base
    end
  end
end

PhoneCallbackAPI::V1::CallbackRequest.create(
  phone: '+33123456788',
  brand_id: 1
)

Accepted parameters are :

Mandatory :
- phone (E.164 format)
- brand_id The id of the brand (and so, which phone number will callback the client)
Optionnal :
- ip_address The client IP address, for logging purpose only
- user_agent The client user agnet, for logging purpose too
- scheduled_at If you want to schedule the callback later, pass this parameter with a ISO 8601 formatted DateTime