Connect Ringba · InboundX docs

Add InboundX as a buyer

In Ringba, add a new buyer for InboundX (some platforms call it a target) and choose the ping type, so Ringba asks us before it sends each call.

From Ringba's documentation Quoted as the platform documents it.

Where to add itDocumented: Ring Trees → Manage Ring Tree Targets → Create Ring Tree Target
The request editorDocumented: Request Settings: URL, HTTP Method, Headers; Basic or Advanced editor. RTB Shareable Tags replaces custom request settings and resets parsing when saved.

Ring Trees › Manage Ring Tree Targets › Create Ring Tree Target

Name

InboundX

Type

RTB ping

Ping URL

Dial

Illustration: the menu path is from Ringba's documentation; the screen may look different.

Paste your ping URL

Put this in the buyer's ping URL. Your key goes where the sample key is, and Ringba fills in the bracketed tokens on every call.

Ping URL

https://app.inboundx.io/api/rtb/ping?key=YOUR_PING_KEY&caller_number=[tag:InboundNumber:Number-NoPlus]&request_id=[Call:InboundCallId]

Keep the key secret: anyone who has it can ping as you.

Not confirmed for Ringba. Where this goes in Ringba's screens isn't documented. What its documentation does say is below; confirm the screen with Ringba.

From Ringba's documentation Quoted as the platform documents it.

Request methodsDocumented: GETPOST
Caller number tokenDocumented: [tag:InboundNumber:Number-NoPlus]
Caller state tokenDocumented: [tag:InboundNumber:State]
Caller ZIP tokenNot confirmed: confirm with Ringba
Other tokensDocumented: conversion_revenue: [Call:ConversionAmount]conversion_payout: [Call:ConversionPayout]
Call ID tokenDocumented: [Call:InboundCallId]
Call ID at ping timeNot confirmed: confirm with Ringba

Accept only when we bid

Tell Ringba how to read our answer. We answer reserved in status when we take the caller; anything else means don't send the call.

Accept the bid when this field

status

equals

reserved

Price field

payout

Not confirmed for Ringba. Where this goes in Ringba's screens isn't documented. What its documentation does say is below; confirm the screen with Ringba.

From Ringba's documentation Quoted as the platform documents it.

How it reads our answerDocumented: Call Acceptance Parsing; Dynamic Bid Parsing; Dynamic Number/SIP Parsing; Dynamic Duration Parsing. Advanced supports JPath, XPath, regular expressions and JavaScript.
Fields its built-in template readsDocumented: bidAmountsipAddressphoneNumberbidTermsexpireInSeconds

Dial the address in the bid

Send the call to the sip_address in each bid, exactly as it is.

Send the call to

sip:YOUR_ROUTE@ADDRESS_FROM_YOUR_SETUP

This one is a sample. Copy yours from your setup message or the portal's Setup page.

Dial the address in this field of each bid

sip_address

Use the address in each bid rather than one you saved.

Not confirmed for Ringba. Where this goes in Ringba's screens isn't documented. What its documentation does say is below; confirm the screen with Ringba.

From Ringba's documentation Quoted as the platform documents it.

A fixed SIP addressNot confirmed: confirm with Ringba
The SIP address from each bidDocumented: Enable Dynamic Number/SIP and configure Dynamic Number/SIP Parsing.
The sip: prefixNot confirmed: confirm with Ringba
How it treats the @Not confirmed: confirm with Ringba

Keep the caller's own number

Leave the caller ID as the caller's own number, and send the call within 15 seconds of our bid. We match the call to its bid by that number: your own number, or a hidden one, won't match.

Not confirmed for Ringba. Where this goes in Ringba's screens isn't documented. What its documentation does say is below; confirm the screen with Ringba.

From Ringba's documentation Quoted as the platform documents it.

Showing the caller's numberDocumented: For upstream Ringba RTB, add exposeCallerId=yes to the request publishers send into Ringba; then the RTT caller tokens can be populated.
Passing the caller ID throughNot confirmed: confirm with Ringba
Ping timeoutDocumented: recommended_ms: 2000dial_timeout_seconds: 10
The caller's number on a SIP transferNot confirmed: confirm with Ringba

Don't convert on call length

This campaign pays when the call qualifies, not after a number of seconds. Turn off any duration conversion for InboundX in Ringba, and ignore seconds in our bid. The postback in the next step tells Ringba which calls paid.

Ignore this bid field

seconds

Not confirmed for Ringba. How Ringba turns off a duration conversion isn't confirmed. Confirm with Ringba that only the postback marks a call as paid.

Tell your platform which calls paid

When a call pays, we call a URL on your platform with these tokens filled in. Here's where to find that URL:

In Ringba, open Integrations, then Webhooks, and copy the webhook URL. Put {CALL_ID} where it says [callUUID] and {PAYOUT} where it says [conversionAmount].

Your call ID

{CALL_ID}

What the call earned, in US dollars

{PAYOUT}

The caller's number

{PHONE}

It should end up like this

https://your-platform.example/conversion?call={CALL_ID}&phone={PHONE}&payout={PAYOUT}

Required: it's the only way Ringba learns which calls paid.

From Ringba's documentation Quoted as the platform documents it.

Where conversions are set upDocumented: Integrations → Webhooks → Create Webhook: Call Token, Revenue Token, Fire Conversions; configure Convert On for postback/webhook.
Conversion URL templateDocumented: https://webhook.ringba.com/hook/{WEBHOOK_ID}?call_id={CALL_ID}&call_revenue={PAYOUT}&sale_successful=yes
Conversion caveatsDocumented: One conversion per inbound call ID; postback window is one month. Later adjustments require the documented manual path.

Integrations › Webhooks › Create Webhook

Name

InboundX

Conversion URL

https://your-platform.example/conversion?call=…

Illustration: the menu path is from Ringba's documentation; the screen may look different.

Test my setup

One test ping through your Ringba setup. We show what arrived, and what to change, as it happens.

Test my setupNo login

Not started

Check your Ringba setup with one test ping

We'll give you a temporary ping URL. Put it in your platform in place of your real one, call your tracking number from any phone, and see what arrived, in plain words.

Your ping arrives
waiting
The caller's number is filled in
waiting
The caller's state is readable
waiting
Every field is under a name we read
waiting
The call arrives inside the hold
not tested yet
The call's caller ID matches the ping
not tested yet

Nothing is billed and no agent is held: every ping gets a test bid that can't be dialled.