To integrate the Companion into your web app, navigate to the Project Deployments tab. Depending on the type of deployment, you can choose to embed a Web Chat Widget, Text iFrame, Voice Widget, or Voice iFrame. Simply copy and paste the provided code snippet to seamlessly embed the AI into your site or app.

​
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

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

In the iframe view 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>

​
Identifying users

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, greeting message, function calls including descriptions, properties or conditions.

To start using variables, you can simply type in { and the autocomplete dropdown will appear where you can create or select pre-existing variables. You can provide test values for the variables to be used in the testing mode.

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.

You can also provide variables via API or widget for 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

​
Webhooks

Our platform supports configuring webhooks both at the organization level and at the project level.

​
Organization-Level Webhooks

You can set a webhook URL at the organization level. This configuration ensures that any events triggered across your organization are sent to the specified webhook URL.

​
Project-Level Webhooks

Webhooks can also be configured at the project level. This allows you to receive project-specific events to a separate webhook URL.

​
Hierarchy of Webhook Configurations

When both organization-level and project-level webhooks are configured, the project-level webhook takes precedence. This means that events related to a specific project will be sent to the project-level webhook, even if an organization-level webhook is also set.

Both custom and system-generated functions are automatically sent to the configured webhook URLs.

Events such as session-start, session-end, interaction-status, and call-recording are sent to the webhook URL.

Ensure your webhook endpoint is properly configured to handle incoming requests.

QuickstartRelease Notes