Roku Ads Manager is a self-service connected TV (CTV) advertising platform that streamlines the ad buying experience from campaign creation to optimization to billing. Using the Roku Ads Manager Conversion API, you can send your call conversion data back to Roku Ads Manager so you can see the success of your Roku ads and optimize them.

This article is for admin users. The tools used in the integration are included with all subscription packages.

This article contains the following sections:

Integrating with Roku Ads Manager
- Prerequisites
How to Integrate Your Ringba Account with Roku Ads Manager
Roku Ads Manager Conversions API Integration Resources and FAQ
- Pixel Field Reference
- What should I do if I need help with my integration?

Integrating with Roku Ads Manager

This guide walks you through connecting Ringba to the Roku Ads Manager Conversions API (CAPI). Once you have configured this integration, Ringba automatically sends call conversion events to Roku Ads Manager via a server-to-server pixel, allowing Roku Ads Manager to attribute phone call conversions back to your CTV ad campaigns.

Because Roku Ads Manager’s CAPI requires the event time in UNIX epoch format, this solution adds a JavaScript snippet to the call flow to format the timestamp before the pixel fires. Roku Ads Manager handles phone number hashing natively when you pass "is_hashed": false in the request payload.

With your Event Group ID, API key, and JS node in place, your Ringba pixel fires automatically based on a call event trigger. This ensures Ringba sends the conversion data to Roku Ads Manager only when the call actually reaches the conversion point you care about, such as when the call is converted.

Prerequisites

For this integration, you must have:

Organization or Account Admin access in Roku Ads Manager.
Admin access in your Ringba account.
The JS call flow node enabled in your Ringba account.
Note: The JS node is included in your subscription, but is not available by default. Contact Ringba support to enable JS node for your Ringba account.

How to Integrate Your Ringba Account with Roku Ads Manager

You complete some of the steps in Roku Ads Manager and some steps in your Ringba account.

How to Get Your Roku Event Group ID in Roku Ads Manager

Use the following steps to get the Roku Event Group ID value, which you need later to set up the pixel:

Sign into Roku Ads Manager at https://ads.roku.com
Go to the Events page at https://ads.roku.com/pixels
Find the Event Group you want to use or create a new one.
Copy and save the Event Group ID someplace secure to use later when you configure the pixel in Ringba.

How to Generate Your Roku CAPI API Key in Roku Ads Manager

Roku Ads Manager's Conversions API uses a bearer token for authentication. Use the following steps to generate the bearer token:

Go to the Events tab and select CAPI.
Click Generate an API key.
Note: This action requires Organization or Account Admin access. If you don't see this option, check your access.
Copy and save the API key somewhere secure to use later when you configure the pixel in Ringba.
Note: API keys do not expire, but if you believe your key has been compromised you can revoke it and generate a new one from the same CAPI settings page.

How to Add a JavaScript Node to Your Call Flow in Ringba

Roku Ads Manager's Conversions API requires the call timestamp as a UNIX epoch integer but Ringba's [Call:CallDateTime] tag provides the time as a formatted string. These steps demonstrate how to add a JS node to reformat the timestamp. Use the following steps:

Sign into your Ringba account.
Navigate to Call Flows > Manage Call Flows and click Create Call Flow.
The call flow canvas appears.
Add a JS node to your call flow and click the node to open the configuration drawer.
Enter the following code in the Script field:
upsertTag('JS', 'epoch', Math.floor(Date.now() / 1000));
Complete and save the call flow.

After this node runs, the epoch value is available in your pixel as [tag:JS:epoch].

How to Configure the Pixel in Ringba

Use the following steps to configure the pixel that sends your call conversion data to Roku AdsManager:

In Ringba, navigate to Integrations > Pixels and click Create Pixel.
Complete the fields:
- Name: Enter a descriptive name for the pixel.
- Fire Pixel On: Select Converted.
- URL: Enter this URL:
  https://events.ads.rokuapi.net/v1/events
- Advanced Options: Toggle on this switch to show more fields.
- HTTP Method: Select POST.
- Content Type: Select application/json.
- Body: Enter the following code.
```
 {
 "event_group_id": "YOUR_EVENT_GROUP_ID",
 "is_hashed": false,
 "events": [[
   {
     "event_name": "CONTACT",
     "event_type": "conversion",
     "event_time": [tag:JS:epoch],
     "event_source": "phone_call",
     "event_id": [Call:InboundCallId],
     "partner_name": "Ringba",
     "user_data": {
       "ph": "[Call:InboundPhoneNumber]"
     }
   }
 ]]
}
```
- Headers key: Enter Authentication
- Headers value: Enter Bearer followed by the Roku API key you created in Roku Ads Manager earlier. For example, Bearer xxxx9xxXXx999xX999xXXXXXxX99x9X9

When you are creating the code for the Body field, note these things:

Replace YOUR_EVENT_GROUP_ID with the Event Group ID you saved from Roku Ads Manager earlier.
"is_hashed": false tells Roku Ads Manager to canonicalize and hash the raw phone number.
For "event name" you can use CONTACT for any inbound call or LEAD if the call reaches a transfer/qualified stage. Other supported values include COMPLETE_REGISTRATION, SIGN_UP, PURCHASE, and more. See the Pixel Field Reference section later in this article.
If a country code is available, you can optionally pass "data_processing_country" (ISO alpha-2) or "country" inside user_data to help Roku Ads Manager canonicalize the phone number more accurately.
In Ringba's pixel body, the events array must be wrapped in double square brackets [[ ]]. Individual tags inside use single square brackets.

How to Assign the Call Flow and Pixel to Your Campaign in Ringba

You must add the call flow and pixel you created to the Ringba campaign you use to track Roku Ads Manager calls. When calls come into that campaign, Ringba uses the call flow with the JS node you set up. If the call meets the criteria to fire the pixel, Ringba programmatically sends the conversion data to Roku Ads Manager.

Use the following steps to add your call flow and pixel to your campaign:

In Ringba, navigate to Campaigns and open the campaign you use to track Roku Ads Manager calls.
Scroll down to the Call Routing section click the Call Flow tab.
In the Call Flow field, select the call flow you created earlier.
Click Save.
Continue to scroll to the Tracking Pixels section and click Add Pixel.
Click the Select Existing option and then select the tracking pixel you created earlier from the Select Pixel drop-down menu and click Add.
Scroll to the bottom and click Save.

Note: Both the call flow and the pixel must be added to the campaign. The JS node in the call flow sets the timestamp tag in a format Roku Ads Manager can use, then the pixel sends the timestamp tag along with the conversion data. If either is missing from the campaign, data does not reach Roku Ads Manager.

How to Test Your Integration

Once you've completed the setup, make a test call to verify the pixel fires and the conversion is received by Roku Ads Manager.

After firing a test conversion, it may take some time for the event to appear in your Roku Ads Manager dashboard. This is expected behavior.

Roku Ads Manager Conversions API Integration Resources and FAQ

For full Roku Ads Manager Conversions API documentation, visit this help site:

Roku Ads Manager Conversions API

For more information on the Ringba features used in this integration, see these articles:

Pixel Field Reference

The table below summarizes the required and recommended fields for call conversion events.

Field	Required	Ringba Source	Notes
event_group_id	Required	Paste from Roku (Step 1)	Identifies your Roku property/app.
is_hashed	Required	Hardcode: false	Tells Roku to hash the phone number on their side.
event_name	Required	Set to CONTACT or LEAD	Use CONTACT for all inbound calls.
event_type	Required	Hardcode: "conversion"	Always "conversion" for call events.
event_time	Required	`[tag:JS:epoch]`	UNIX epoch int from the JS node.
event_source	Recommended	Hardcode: "phone_call"	Tells Roku this is a call conversion.
user_data.ph	Required*	`[Call:InboundPhoneNumber]`	Raw phone number — Roku hashes it (is_hashed: false).
partner_name	Recommended	Hardcode: "Ringba"	Identifies Ringba as the sending partner.
event_id	Recommended	[Call:InboundCallId]	Provides the unique Ringba Inbound Call ID for the conversion event, allowing Roku to validate event attribution and prevent duplicate reporting.

* At least one user identifier is required (ph, em, client_ip_address, or a mobile ad ID). A raw phone number with is_hashed: false is the most natural choice for call traffic — Roku Ads Manager handles canonicalization and hashing on their end.

What should I do if I need help with my integration?

If you have any questions or need additional help, please reach out to our support team via chat or email at support@ringba.com.