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).

The two 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:

https://api.ap3api.com/v1/talk/session

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: https://api.au.ap3api.com/
  • Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

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

shell

curl --request POST 'https://api.ap3api.com/v1/talk/session' \ //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": "john.smith@example.com", "str::name": "John Smith" } "location": { "source_ip": "119.19.0.218" } }'

1

The API endpoint for requesting a Talk session token.

2

Your custom API key.

3

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.

4

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.

5

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. https://ortto.app/myinstance/cdp/people/006281d8ff95c3ed70b70801/activities?from=cdp-filter&key=people-all-).

6

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

json

{ "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:

javascript

<!-- 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>', 'https://capture-api-master.autopilotapp.com/', {cookieDomains: ['.brand.app'], 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 = "https://cdn31.ink/app.js"; 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:

javascript

ap3c.init('<capture key>', 'https://capture-api-master.autopilotapp.com/', {cookieDomains: ['.brand.app'], 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.