Create a verified Talk session

When visitors or contacts begin a conversation in Talk, they may be identified as Not verified (not secure) in the conversation message bar.

Example of a contact which is not verified

A verified/secure contact is someone who has signed-in to your website or web-based app, and confirmation of their identity and session data is passed to the Talk widget. (When a contact is verified, there will be no label or alert at the message bar.)

An unverified contact is someone who may be signed-in to your site, but if their credentials and session data are not passed to the Talk widget, then the widget doesn’t know that the person’s session is secure and marks the contact as Not verified.

Verifying contacts will help agents such as those in a customer support role to know they are speaking to an authentic contact, not just someone what has started a conversation using that contact’s email address.

You tell the Talk widget that a contact is verified by sending a request to Ortto’s API, which will return a token to be added in your website’s tracking code. The token is then recognized by the Talk widget to identify the contact as being securely signed-in, and enable your Talk agents to access the contact’s data, including browser session history, via the customer data platform (CDP).

If you have a page where customers and users can log in (such as a single-page application), you can restart the Talk messenger after a customer logs in and set the conversation as verified using the session token.

The three key steps to creating a Talk session are described below:

Request a Talk session token

Requests for a Talk session token are submitted as a single POST method call to the following URL:

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

  • Australia:
  • Europe:

For example:<entity/endpoint>

All other Ortto users will use the default service endpoint (

In a given request, the actual people’s data retrieved from the CDP is determined by the specified fields values.

Each copyable code example on this page is annotated with callouts along with associated explanations.

cURL example

cURL example request for a Talk session token for a contact


curl --request POST '' \ //1 --header 'X-Api-Key: YOUR-API-KEY-HERE' \ //2 --header 'Content-Type: application/json' \ --data-raw '{ //3 "merge_by": ["str::email"], //4 "merge_strategy": 2, "find_strategy": 0, "skip_non_existing": false, //5 "person_id": "006281d8ff95c3ed70b70801" //6 "fields": { "str::email": "", "str::name": "John Smith" } "location": { "source_ip": "" } }'


The API endpoint for requesting a Talk session token.


Your custom API key.


The merge_by field value/s in this request, which can be used to override the Merge strategy main and fallback associations configured for your custom API key. When this member is present and contains two values, the first value is the main association field, and the second is the fallback. If this member is not specified in the request, the Merge strategy associations configured for your custom API key in this request () are used instead.


The actual merge strategy, which can be used to override the default value of 2 (Overwrite existing). If this member is not specified in the request, then the default value of 2 (Overwrite existing) is used instead.


The optional ID for the contact in your CDP. You can obtain the person_ID value using the get endpoint to retrieve one or more people. Or, find the person’s ID in the Ortto app by viewing the contact’s profile and copying the ID from the URL (e.g.


The fields array object containing a person’s data (as person fields) to be associated with the session.

The str::email and str:name fields are required, to ensure that Talk can associate the person with a CDP record.

Response example

The following response payload is an example from the cURL example above, which retrieved select data (specified through fields in the request) from a person’s record in your Ortto CDP.

Response payload example from the cURL request above


{ "session_id": "000000000000000000000000", "token": "<response token>", "person_id": "006281d8ff95c3ed70b70801", "person_status": "by-id" }

Add the Talk token to your tracking code

Once you have the response payload from your Talk session token request, copy the token value and configure the initialize function (ap3c.init) in your capture code to include it:


<!-- Ortto yourorttoinstance capture code --> <script> window.ap3c = window.ap3c || {}; var ap3c = window.ap3c; ap3c.cmd = ap3c.cmd || []; ap3c.cmd.push(function() { ap3c.init('<capture key>', '', {cookieDomains: [''], link: 'h', disableWidgets: false, talk: {"token":"<response token>"}}); ap3c.track({v: 0}); }); ap3c.activity = function(act) { ap3c.act = (ap3c.act || []); ap3c.act.push(act); }; var s, t; s = document.createElement('script'); s.type = 'text/javascript'; s.src = ""; t = document.getElementsByTagName('script')[0]; t.parentNode.insertBefore(s, t); </script>

If required, you can also specify the cookie path (cookiePath) after the token. This is helpful if you have multiple Ortto accounts (instances) and you have one or more contacts that are CDP records in each of those instances. By setting the cookie path, you specify which instance’s data you want to make available for the contact’s Talk session. Add the cookie path like so:


ap3c.init('<capture key>', '', {cookieDomains: [''], link: 'h', disableWidgets: false, talk: {"token":"<response token>" ,"cookiePath":"/yourinstance/"}});

Once your tracking code is configured, the Talk widget will be able to recognize verified contacts when they initiate or are involved in a conversation.

NOTE: Contact verification needs to be performed per conversation; it won't be applied per contact. If a conversation was created before a contact became authorized or had their identity confirmed, the contact will remain unverified for that conversation.

Switch to a verified session

If a contact is unknown (e.g. they have not yet logged in to your app and been identified via your Ortto tracking code), when they start a Talk session (start a conversation via the Talk messenger widget), they will be considered not verified.

After the unknown contact has been recognized by your website or app (e.g. they’ve logged in to your app), you can switch to a verified Talk session using the setVerifiedSession function.

This will restart the Talk messenger with the verified contact’s details (resulting in a verified session), and means that you do not need to reload the page to achieve the same result. This is helpful when you have a single page application that your users log into, and you want verified Talk sessions to begin after a customer has logged in to their account.

The setVerifiedSession function uses the <response_token> you received in response to the POST method request to

Switch to a verified session by running the following function:{token: '{{<reponse_token>}}'});

NOTE: If setVerifiedSession is run after a session has already started, when the Talk messenger reloads, it will start a new session (resulting in 2 separate sessions for this contact). The initial session may show the contact as known, but unverified. The second session will show the contact as both known and verified.