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).
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 of2
(Overwrite existing) is used instead.5
The optional ID for the contact in your CDP. You can obtain the
person_ID
value using theget
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
andstr: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.