For integrating the Companion Widget into your web app, go to Customize page (from the left menu) and simply copy-paste embed code we provided.

The widget bubble will appear in right or left bottom corner of your web page. After clicking on Bubble your Companion will appear and your users will be ready to communicate.

​
Initialization

The companion widget inside the iframe now requires initialization, which could be done using the method initializeAssistant provided by the CompanionWidget library, loaded alongside the integration script.

Before running the initialization method, the iframe should be added to the DOM, loaded properly, and ready for receiving the data. The iframe fires the event “companion-iframe-loaded” when properly loaded.

Initial data should be an empty object or contain variables as keys to match the prompt variables.

Example of how to initialize the Companion widget with data on the iframe loads:

...
<script
  id="companion-widget-script"
	....
></script>
<script>
  window.addEventListener("companion-iframe-loaded", function() {
    CompanionWidget.initializeAssistant({
      userName: "Bob",
      memoryNotes: "Additional information about the user",
    });
  });
</script>

The method CompanionWidget.initializeAssistant could be called at any time later to provide fresh data to the companion.

​
Customization

​
Appearance

There are two appearance types of the widget: bubble (default) and iframe.

In the bubble mode script will create a widget button that expands into the modal window with a companion iframe.

In the iframe mode it will embed an <iframe> into the DOM element with an ID specified in the Container ID property:

On the page where you want to embed the Companion iframe, you should add a container element with the specified ID:

<script
  id="companion-widget-script"
	....
></script>
<body>
    <h1>Test Companion iframe</h1>
    <div id="companion-container">
    </div>
</body>

​
Advanced settings

Widget integration supports anonymous voice communication out-of-the-box.

But we support few advanced settings to extend this.

To make chat more personal for users so Companion will remember some facts about user and previous interaction context you can provide data-unique-id so we can identify different end users, save some data and use it in future interaction. Value of this param can be any unique string less than 30 characters.

​
Function calls

Expand your companion’s abilities by creating custom functions in the builder.

After clicking on the “Add new function” button, a form with all the function settings will be available.

You can set your function name and description that will appear later in the list of the companion’s existing functions.

Other than that, you can specify different properties you need with type (object, string, boolean, number) and make each of them required/not required.

Once you have configured the functions, don’t forget to save the configuration to apply the changes.

​
Configure Server URI

You can also configure the server URI to receive the function call results on your server via an HTTP request. This configuration expands your companion’s capabilities and provides a richer, more interactive user experience.

Providing results and context using server URI is working out of the box for text and SMS modes.

For the voice mode, you should enable RAG option in the configuration settings. Without this option, the server’s response will not be included in the voice call.

  • Server URI: This is the endpoint where we’ll send a HTTP POST request with the function call results.
  • Secret Key: We’ll include this key in the request headers("x-ck": <Secret Key>), allowing you to verify that the incoming requests are genuinely from our API.

The request format will be as follows:

{
  "id": "<function_call_id>",
  "function": {
    "name": "<function_name>",
    "arguments": {}
  }
}

Upon processing the request, your server can send back a response in the valid JSON format. It could be a string, a number, an object, an array, or any other data structure.

​
Custom variables

Our system allows you to enhance your companion’s prompts by incorporating dynamic variables. These variables can be used to insert specific information or context into the prompt.

To start using variables, you can simply insert into prompt text variables in the format {variable_name}.

Example:

Prompt with variables: "Hello {user_name}! Based on your {preference} preference, I recommend {recommendation}."

This approach allows for more personalized and context-aware interactions between the companion and users.

To define and populate variables, we have two options for different use cases.

If you are testing in the builder, you can open the settings modal from navigation (COG icon).

Here you can define a list of variables used in the prompt and set default values for them.

Another way could be used at the production stage.

  • API Endpoint Integration: When initiating a call with the companion via our API endpoint, include a variables property in your request. This property should contain key-value pairs representing your variables. Example API request:
curl --request POST \
  --url https://api.outrival.com/rest/v1/assistants/phone-calls/initiate \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <YOUR_API_KEY>' \
  --data '{
  "assistantId": "<ASSISTANT_ID>",
  "phoneNumber": "+11111111111",
  "variables": {
    "testProperty": "value"
  }
}'
  • Embed Code Integration: When using our embed code on your website, you should initialize the companion with variables using the provided method. Example embed code usage:
<script>
  window.addEventListener("companion-iframe-loaded", function () {
    CompanionWidget.initializeAssistant({
      userName: "Bob",
      memoryNotes: "Additional information about the user",
    });
  });
</script>

Note: Ensure that all used variables are properly defined and populated.

​
Twilio connection

Our application supports custom Twilio connection for phone calls and SMS. To use it you should provide us:

  • Twilio Phone Number - Twilio Account SID - Twilio Auth Token

For SMS integration you should set up Messaging Service on the Twilio side.

Provide to us your Messaging Service SID.

Setup integration for you Messaging Service and setup webhook with next Request URL: https://api.outrival.com/webhooks/twilio/intercept-sms

Builder QuickstartOutRival Voice Call SDK