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.

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).

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. Minimal Code Examples

Python

from twilio.twiml.voice_response import VoiceResponse, Dial, Application
import hmac
import hashlib
 
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()
app = Application(retreaver_application_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=str(retreaver_company_id))
app.parameter(name="RetreaverSignature", value=signature)
 
dial.append(app)
response.append(dial)
 
print(str(response))

Node.js

const crypto = require('crypto');
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 = crypto
  .createHmac('sha256', companySecret)
  .update(canonical, 'utf8')
  .digest('hex');
 
const twiml = new twilio.twiml.VoiceResponse();
const dial = twiml.dial();
const app = dial.application(retreaverApplicationSid);
 
app.parameter({ name: 'OriginalTo', value: originalTo });
app.parameter({ name: 'OriginalCallSid', value: originalCallSid });
app.parameter({ name: 'RetreaverPhoneNumber', value: retreaverNumber });
app.parameter({ name: 'RetreaverCompanyId', value: String(retreaverCompanyId) });
app.parameter({ name: 'RetreaverSignature', value: signature });
 
console.log(twiml.toString());

Ruby

require "twilio-ruby"
require "openssl"
 
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(retreaver_app_sid) do |app|
      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();
$app = $dial->application($retreaverAppSid);
 
$app->parameter(['name' => 'OriginalTo', 'value' => $originalTo]);
$app->parameter(['name' => 'OriginalCallSid', 'value' => $originalCallSid]);
$app->parameter(['name' => 'RetreaverPhoneNumber', 'value' => $retreaverNumber]);
$app->parameter(['name' => 'RetreaverCompanyId', 'value' => (string)$retreaverCompanyId]);
$app->parameter(['name' => 'RetreaverSignature', 'value' => $signature]);
 
echo $response;

Help us improve this article or request new support guides.

Previous

Credit Card Verification

Next

Why are my calls being disconnected?

On this page