Voice Channels (Custom Voice Channels)

Custom Voice Channels

Setting up a customer Voice channel allows you to connect a third party Voice channel that Re:amaze does not support natively, and lets you build your own Voice integration with Re:amaze.

To log call events for voice channels, you will need to make a POST request to Re:amaze. Useful event examples are when a call starts, call ends, call is missed, if there is a voicemail, a call recording, etc.

Authentication

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

Here are some code examples on 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))

When logging a message on a voice channel in Re:amaze, here's how you would generate the request:

# 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

Creating the Voice message in Re:amaze

To log a call event, you'll need to 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 then respond with a status code of 2xx if the request was successful. An status code of 5xx is a temporary failure and the request should be retried. A status code of 4xx usually means that the request does not parse and should not be retried before fixing the request parameters.