Chat Widget & SDK

The Outrun chat widget puts a chat window on your website so visitors can talk to your agents. This page shows how to install it with the Outrun web SDK, identify visitors and set up the welcome message.

Create a website source

1. In the sidebar, go to Data > Sources and add a Website source.
2. Enter a Source Name, for example Marketing Site.
3. Under Allowed Domains, add each domain the widget runs on. You need at least one. Use *.example.com to include example.com and all its subdomains.
4. Select Create Source.
5. Copy the Source ID and the Bearer Token. The token is shown only once.

The bearer token is placed in your web page, so anyone can read it. It is not a secret.

Install the SDK

Paste this code before the closing </body> tag on every page that should show the widget. Replace the placeholders with your workspace ID, Source ID and Bearer Token.

<script src="https://cdn.getoutrun.com/sdk/outrun.min.js"></script>
<script>
  outrun.init({
    apiKey: '<bearer-token>',
    workspaceId: '<workspace-id>',
    streamId: '<source-id>'
  });
  outrun.chat.init({
    sourceId: '<source-id>',
    token: '<bearer-token>'
  });
</script>

outrun.init needs apiKey, workspaceId and streamId. Without them the SDK logs an error and does not start.

The chat launcher appears in the bottom-right corner once an active agent answers chat for this source. See setting up agents.

Note: If you copy the embed code shown in Outrun after creating the source, check that its script URL is https://cdn.getoutrun.com/sdk/outrun.min.js.

Chat options

outrun.chat.init accepts these options:

Control the widget from your code

For example, open the chat when someone selects a help button:

<button onclick="outrun.chat.open()">Chat with us</button>

Identify visitors

Call outrun.identify after outrun.init to record details about the visitor. Pass your own user ID and traits, or traits alone:

outrun.identify('user-123', {
  email: '[email protected]',
  firstName: 'Jane',
  lastName: 'Smith',
  company: 'Acme Pty Ltd'
});

Without a signature, outrun.identify only saves the traits on this browser's visitor profile. It never links the browser to an existing person, and a self-reported email is kept as a trait: Outrun does not use it to find or create a contact.

To link the visitor to a known person, sign the user ID on your server: the hex HMAC-SHA256 of the user ID, keyed with the website source's identity secret. Then pass the signature as a third argument:

outrun.identify('user-123', { company: 'Acme Pty Ltd' }, {
  sourceId: '<source-id>',
  externalIdSignature: '<signature-from-your-server>'
});

You can instead pass the same externalId and externalIdSignature to outrun.chat.init. outrun.identify reuses them when the user ID matches. Even with a signature, only the user ID is verified, so email stays a trait.

Outrun ignores traits it manages itself: plan, customerId, lifecycleStage, enterpriseIntent, segment, engagementScore, nudgeCount and lastNudgedAt.

Outrun treats a chat visitor as verified only when outrun.chat.init receives an externalId and a matching externalIdSignature. If the signature does not match, the visitor can still chat but is not treated as verified. Outrun has no signing endpoint, so always sign on your own server. The Outrun app does not display a website source's identity secret.

Set up the chat welcome

1. Go to Data > Sources and open the website source.
2. In Chat welcome, set any of these:
   • Greeting: the first message visitors see when they open the chat. Up to 280 characters.
   • Suggested questions (up to 4): buttons that send the question when selected. Up to 80 characters each.
   • Show a proactive teaser near the chat icon (once per visitor per day): a message that appears next to the launcher. Set Delay before showing from 3 to 120 seconds. The default is 20.
   • Page-specific teasers: a different teaser for pages whose path starts with a prefix you set. Up to 5.
   • Never show on these paths: paths where the teaser never appears. Up to 10.
3. Select Save welcome.

Welcome text is shown as plain text. Outrun removes any markup. The teaser does not show once the visitor has opened the chat.

Content security policy

If your site sets a Content Security Policy, it must allow:

• the script from https://cdn.getoutrun.com
• connections to https://api.getoutrun.com and wss://api.getoutrun.com
• the style elements the widget adds to the page

Troubleshooting