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.

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:

1. Request a Talk session token.
2. Add the Talk token to your tracking code.
3. Switch to a verified Talk session (optional).

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

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"
        }
      }'

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.

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 https://api.ap3api.com/v1/talk/session.

Switch to a verified session by running the following function:

window.ap3c.talk.setVerifiedSession({token: '{{<reponse_token>}}'});