Compose a new Talk conversation

The Compose Talk endpoint is used to create a new Talk conversation, which could be helpful if conversation requests are coming from an external form, or other integrations not natively supported by Ortto.

This page provides descriptions of this endpoint's:

request resource and method
valid parameters, headers and request body values, as well as
the response payload

HTTP method and request resources

Talk endpoint


 POST https://api.ap3api.com/v1/talk/compose

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

Path and query parameters

This endpoint takes no additional path and/or query parameters.

Headers

This endpoint requires a custom API key and content type (application/json for the request body) in the header of the request:

X-Api-Key: CUSTOM-PRIVATE-API-KEY
Content-Type: application/json

Request body

The request body consists of a JSON object with the valid elements listed in the table below.

Provide the details of the person starting the conversation, as well as the subject and content of the conversation per the sample JSON request below:

json
 {  
  "fields": {
    "str::first": "Joe",
    "str::last": "Citizen",
    "str::email": "some@email.com"
  },
  "merge_by": [
    "str::email"
  ],
  "conversation": {
    "subject": "Question about pricing",
    "messages": [
      {
        "type": "text",
        "body": "Do you provide discounts for multi-year commitments?"
      },
      {
        "type": "html",
        "body": "<html>Do you provide <b>discounts</b> for <i>multi-year</i> commitments?</html>"
      }
    ]
  }
}

Depending on the merge strategy configured for your custom API key, composing a talk conversation for a person who does not match an existing contact in your CDP may create that person as a new contact. By default, all people added via the API are considered to be "opted in" for email subscription permission.

To specify email subscription permission, include in fields:

bol::p — a field representing permission that takes a value of true or false

str::s-ctx — a field used to create a message identifying how the person was subscribed/unsubscribed.

Valid request body elements

The following table lists all valid, optional request body elements (arrays, objects, or fields), which are available to this endpoint.

Element		Type	Description
`fields`		Object containing person fields.	The object containing the fields for a person being created or updated in your Ortto account’s CDP. This person is either created or updated in Ortto’s CDP based on these criteria: If this `fields` object contains a person field ID whose value matches the `merge_by` ID value submitted in this request, and this person field’s value does not match that of an existing person in Ortto’s CDP, then Ortto creates this person as a new record. Otherwise, if the person field ID value does already match that of an existing person in Ortto’s CDP, then Ortto updates the fields of that person’s record in the Ortto CDP, according to the `merge_strategy` set for your Ortto custom API data source.
`merge_by`		`array` of one or two `string` values	The `merge_by` element’s array allows up to two field ID values that specify the person fields used to determine whether the people’s records are either created or updated in your Ortto account’s CDP. When the value of the person field ID (determined by the relevant `merge_by` value), submitted in this request matches that of an existing person in Ortto’s CDP, then this person’s record is updated in the CDP and where appropriate, existing field values are merged according to the `merge_strategy` set for your Ortto custom API data source. Otherwise, Ortto creates a new person’s record in the CDP. These values override the default person fields associated with the custom API key with the `merge_by` fields submitted in this request. These default field values are defined by the Merge strategy associations configured for this custom API key. If a `merge_by` element is not specified in the request, then these default person field values are utilized instead. The first of these values determines the main `merge_by` person field utilized by Ortto in the request, whereas the second (optional) value determines the fallback `merge_by` person field (which behaves as a backup should the first field - e.g. a custom field - not be available within the person’s record of Ortto’s CDP).
`conversation`	`subject`	`string`	A subject to summarise the content of the conversation.
	`messages`	`array` of objects	The `messages` array consists of an array of objects where each object contains content to include in the conversation. Each object can contain: `type` of content `body` of the content
	`messages` > `type`	`string`	Possible values for the type of content: text html
	`messages` > `body`	`string`	Provide the text or HTML content of the message.

Note: When sending message content as HTML, you can include images either by providing an external URL or as base64 encoded.

E.g. <img src=\"data:image/png;base64,iVBOR…….RK5CYII=\"> or

<img src=\"https://image-url….\" width=\"300\" height=\"200\" />

Response payload

The response payload consists of a JSON object with the elements listed in the table below.

The following JSON object is an example of people’s data that Ortto retrieves from your Ortto account’s CDP after a request to this endpoint.

Example compose talk conversation response payload from Ortto’s CDP

json
 {
  "conversation_id": "0063f2c474bc15d72affcdcc",
  "person_id": "0063f2c474449cd58a4c5600",
  "person_status": "created"
}

Response payload elements

The following table lists all elements (arrays, objects, or fields) in the response from a request to this endpoint.

Element	Type	Description
`conversation_id`	`string`	The unique identifier for the conversation.
`person_id`	`string`	The unique identifier for the CDP contact.
`person_status`	`string`	Identifies whether a new contact has been `created` for this conversation or it has been `merged` to an existing contact.