Custom Voice Channel Integration

Re:amaze allows you to connect third-party voice providers that are not natively supported by building a custom voice channel integration. To log call events, you will need to make POST requests to Re:amaze. Useful events to log include call started, call ended, missed call, voicemail, and call recording.

Authentication

Each request going into and out of Re:amaze must include a X-Reamaze-Hmac-SHA256 header. This is the base64-encoded SHA256 HMAC hash generated using the channel's shared secret, defined when the channel is created, along with the data sent in the request. This allows Re:amaze to verify requests coming from you, and allows you to verify requests coming from Re:amaze.

Code examples for generating the SHA256 HMAC:

// PHP:
$data = '{"id":"1","body":"hello"}';
$shared_secret = 'your_shared_secret';
$calculated_hmac = base64_encode(hash_hmac('sha256', $data, $shared_secret, true));

// RUBY:
require 'base64'
require 'openssl'
SHARED_SECRET = 'your_shared_secret'
data = '{"id":"1","body":"hello"}'
calculated_hmac = Base64.strict_encode64(OpenSSL::HMAC.digest('sha256', SHARED_SECRET, data))

Example for logging a voice event to Re:amaze:

# RUBY

require 'rubygems'
require 'faraday'
require 'base64'
require 'openssl'

# The channel's shared secret
SHARED_SECRET = 'my_shared_secret'

connection = Faraday.new(url: 'https://www.reamaze.io/incoming/voice') do |faraday|
  faraday.request :json
  faraday.adapter Faraday.default_adapter
end 

response = connection.post do |req|
  data = {
    id: 'voice-call-id', 
    direction: 'outbound', # optional, defaults to 'inbound'
    to: {
      name: 'Foo', # this is optional
      phone: '+16501234567' # if outbound direction, this is the customer number, otherwise this is the channel phone number
    },
    from: {
      name: 'Bar',
      phone: '+15105559999' # if outbound direction, this is the channel phone number, otherwise this is the customer phone number
    },
    body: 'Call Started - From John Doe',
    created_at: '2019-08-06T23:21:15+0000', # optional - iso8601 datetime of when voice event was created
    attachments: [ # optional array of attachment urls
      'https://www.example.com/voice-recording.wav'
    ],
    thread_id: 'call-session-id-1234',  # optional, but highly recommended - unique id identify the entire call session. Call events with the same thread_id will be grouped in the same conversation inside Re:amaze. When left blank, the call event will be attributed to the customer's most recent call session in Re:amaze that happened within the past hour.
    assignee: { # optional - when provided and if the email matches a staff email, the related conversation will be assigned to that staff user. Absence of this parameter will not unassign the conversation.
      email: "staffemail@example.com"
    }
  }.to_json

  digest = OpenSSL::Digest.new('sha256')
  calculated_hmac = Base64.encode64(OpenSSL::HMAC.digest(digest, SHARED_SECRET, data)).strip

  req.headers['X-Reamaze-Hmac-SHA256'] = calculated_hmac
  req.headers['Content-Type'] = 'application/json'
  req.body = body
end

Log a voice event in Re:amaze

To log a call event, send a POST request to https://www.reamaze.io/incoming/voice with the following data:

{
  "id": "voice-call-event-id",
  "direction": "inbound",
  "to": {
    "name": "Support",
    "phone": "+16501234567"
  },
  "from": {
    "name": "Customer name",
    "phone": "+15105559999"
  },
  "body": "Call ended - duration: 0:30:05",
  "attachments": [
    "https://www.example.com/call-recording.wav"
  ],
  "created_at": "2019-08-06T23:21:15+0000",
  "thread_id": "call-session-id-1234",
  "assignee": {
    "email": "staffemail@example.com"
  }
}

Re:amaze will respond with a status code of 2xx if the request was successful. A status code of 5xx indicates a temporary failure and the request should be retried. A status code of 4xx typically means the request could not be parsed and should not be retried until the request parameters are corrected.