Retreaver
Contact SupportOpen Retreaver
Integrations

Twilio Application Connect

Quick summary

Twilio Application Connect lets you hand off calls from your own Twilio apps directly into Retreaver. This gives you the flexibility of using Twilio's and Retreaver's features in tandem.

Twilio Application Connect – Quickstart

Twilio Application Connect lets you hand off calls from your own Twilio apps into Retreaver using a signed payload, instead of wiring every inbound DID directly to Retreaver. Your IVRs and numbers stay in Twilio; Retreaver receives an authenticated request that says exactly which campaign and company to route the call to.

In this quickstart you will learn:

1. Prerequisites

  • Twilio account with a Voice application (Studio Flow, Function, or webhook).
  • Retreaver account with:
    • Twilio Application Connect feature enabled. You should contact support to get this enabled.
    • At least one Retreaver number (campaign number).
    • Access to the company’s Twilio Application Connect secret (visible on the Company page for superusers).
    • Twilio Application SID . Reach out to our support team to receive your Application SID.

Keep the secret safe: Treat the Twilio Application Connect secret like a password. Never expose it in client-side code, logs, or public repositories.

2. What You Send to Retreaver

When your Twilio app is ready to hand a call to Retreaver, it:

  1. Uses <Dial><Application> to dial your Retreaver TwiML Application.
  2. Sends a small signed payload using <Parameter>s:
    • OriginalTo – the number originally dialed in your Twilio app.
    • OriginalCallSid – the Twilio CallSid of the original call leg.
    • RetreaverPhoneNumber – the Retreaver campaign number you want to route to.
    • RetreaverCompanyId – the Retreaver company ID.
    • RetreaverSignature – HMAC-SHA256 of all the above using your Retreaver company secret.

Retreaver recomputes the same signature; if it matches, the call is routed as if it had dialed RetreaverPhoneNumber directly.

3. Example TwiML Hand‑Off

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Application applicationSid="APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX">
      <Parameter name="OriginalTo" value="+14155550123" />
      <Parameter name="OriginalCallSid" value="CA1234567890abcdef1234567890abcdef" />
      <Parameter name="RetreaverPhoneNumber" value="+18005551234" />
      <Parameter name="RetreaverCompanyId" value="1234" />
      <Parameter name="RetreaverSignature" value="hmac_sha256_hex_here" />
    </Application>
  </Dial>
</Response>

Your Twilio app code is responsible for computing RetreaverSignature using the canonical string and the Retreaver company secret.

4. Setting it up via Twilio Functions

You could also set it up directly in the Twilio Console by using Twilio Functions .

  1. Add crypto-js as a dependency to your function. Prefer using the latest version, i.e. set the version to "latest".
  2. Add the following environment variables to your function:
  • RETREAVER_APPLICATION_SID - Reach out to our support team to receive your Application SID
  • RETREAVER_SECRET - Follow these steps outlined in Prerequisites to find out what the value should be
  • RETREAVER_COMPANY_ID - Your Retreaver company id.
  • RETREAVER_NUMBER - The number associated to the Retreaver Campaign that you'd like to receive a call to.
  1. Add the following code to your function:
// This is your new function. To start, set the name and path on the left.
const CryptoJS = require("crypto-js");
 
exports.handler = function(context, event, callback) { 
  const originalTo = event.To;
  const originalCallSid = event.CallSid;
 
  const canonical = `${originalTo}:${originalCallSid}:${context.RETREAVER_NUMBER}:${context.RETREAVER_COMPANY_ID}`;
  const signature = CryptoJS.HmacSHA256(canonical, context.RETREAVER_SECRET).toString(CryptoJS.enc.Hex);
 
  const twiml = new Twilio.twiml.VoiceResponse();
  const dial = twiml.dial();
 
  const application = dial.application();
  application.applicationSid(context.RETREAVER_APPLICATION_SID);
 
  application.parameter({ name: 'OriginalTo', value: originalTo });
  application.parameter({ name: 'OriginalCallSid', value: originalCallSid });
  application.parameter({ name: 'RetreaverPhoneNumber', value: context.RETREAVER_NUMBER });
  application.parameter({ name: 'RetreaverCompanyId', value: String(context.RETREAVER_COMPANY_ID) });
  application.parameter({ name: 'RetreaverSignature', value: signature });
  
  console.log(twiml.toString());
 
  return callback(null, twiml);
};

5. Minimal Code Examples

Python

import hmac
import hashlib
 
from twilio.twiml.voice_response import VoiceResponse, Dial, Application
 
original_to = "+14155550123"
original_call_sid = "CA1234567890abcdef1234567890abcdef"
retreaver_number = "+18005551234"
retreaver_company_id = 1234
company_secret = "YOUR_RETREAVER_TWILIO_APP_CONNECT_SECRET"
retreaver_application_sid = "APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 
canonical = f"{original_to}:{original_call_sid}:{retreaver_number}:{retreaver_company_id}"
signature = hmac.new(
    company_secret.encode("utf-8"),
    canonical.encode("utf-8"),
    hashlib.sha256,
).hexdigest()
 
response = VoiceResponse()
dial = Dial()
 
application = Application()
application.application_sid(retreaver_application_sid)
 
application.parameter(name="OriginalTo", value=original_to)
application.parameter(name="OriginalCallSid", value=original_call_sid)
application.parameter(name="RetreaverPhoneNumber", value=retreaver_number)
application.parameter(name="RetreaverCompanyId", value=str(retreaver_company_id))
application.parameter(name="RetreaverSignature", value=signature)
 
dial.append(application)
response.append(dial)
 
print(str(response))

Node.js

const CryptoJS = require('crypto-js');
const twilio = require('twilio');
 
const originalTo = '+14155550123';
const originalCallSid = 'CA1234567890abcdef1234567890abcdef';
const retreaverNumber = '+18005551234';
const retreaverCompanyId = 1234;
const companySecret = 'YOUR_RETREAVER_TWILIO_APP_CONNECT_SECRET';
const retreaverApplicationSid = 'APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
 
const canonical = `${originalTo}:${originalCallSid}:${retreaverNumber}:${retreaverCompanyId}`;
const signature = CryptoJS.HmacSHA256(canonical, companySecret).toString(CryptoJS.enc.Hex);
 
const twiml = new twilio.twiml.VoiceResponse();
const dial = twiml.dial();
 
const application = dial.application();
application.applicationSid(retreaverApplicationSid);
 
application.parameter({ name: 'OriginalTo', value: originalTo });
application.parameter({ name: 'OriginalCallSid', value: originalCallSid });
application.parameter({ name: 'RetreaverPhoneNumber', value: retreaverNumber });
application.parameter({ name: 'RetreaverCompanyId', value: String(retreaverCompanyId) });
application.parameter({ name: 'RetreaverSignature', value: signature });
 
console.log(twiml.toString());

Ruby

require "openssl"
require "twilio-ruby"
 
original_to          = "+14155550123"
original_call_sid    = "CA1234567890abcdef1234567890abcdef"
retreaver_number     = "+18005551234"
retreaver_company_id = 1234
company_secret       = "YOUR_RETREAVER_TWILIO_APP_CONNECT_SECRET"
retreaver_app_sid    = "APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 
canonical = "#{original_to}:#{original_call_sid}:#{retreaver_number}:#{retreaver_company_id}"
signature = OpenSSL::HMAC.hexdigest("SHA256", company_secret, canonical)
 
response = Twilio::TwiML::VoiceResponse.new do |r|
  r.dial do |d|
    d.application do |app|
      app.application_sid(retreaver_app_sid)
      app.parameter(name: "OriginalTo", value: original_to)
      app.parameter(name: "OriginalCallSid", value: original_call_sid)
      app.parameter(name: "RetreaverPhoneNumber", value: retreaver_number)
      app.parameter(name: "RetreaverCompanyId", value: retreaver_company_id.to_s)
      app.parameter(name: "RetreaverSignature", value: signature)
    end
  end
end
 
puts response.to_s

PHP

<?php
 
use Twilio\TwiML\VoiceResponse;
 
$originalTo          = '+14155550123';
$originalCallSid     = 'CA1234567890abcdef1234567890abcdef';
$retreaverNumber     = '+18005551234';
$retreaverCompanyId  = 1234;
$companySecret       = 'YOUR_RETREAVER_TWILIO_APP_CONNECT_SECRET';
$retreaverAppSid     = 'APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
 
$canonical = sprintf(
    '%s:%s:%s:%s',
    $originalTo,
    $originalCallSid,
    $retreaverNumber,
    $retreaverCompanyId
);
 
$signature = hash_hmac('sha256', $canonical, $companySecret);
 
$response = new VoiceResponse();
$dial = $response->dial();
$application = $dial->application();
$application->applicationSid($retreaverAppSid);
 
$application->parameter(['name' => 'OriginalTo', 'value' => $originalTo]);
$application->parameter(['name' => 'OriginalCallSid', 'value' => $originalCallSid]);
$application->parameter(['name' => 'RetreaverPhoneNumber', 'value' => $retreaverNumber]);
$application->parameter(['name' => 'RetreaverCompanyId', 'value' => (string)$retreaverCompanyId]);
$application->parameter(['name' => 'RetreaverSignature', 'value' => $signature]);
 
echo $response;

Help us improve this article or request new support guides.

Previous

Pay-Per-Call Features To Optimize Your Conversion Performance

Next

How to Set Up Your First Call Tracking Campaign

On this page