Introduction
This document describes the resources that make up the official Yonyx REST API v3. The API base URL is https://developer.yonyx.com/y/apiv3/. If you have any questions please contact us.
API key and API secret
🔗 After you sign up with Yonyx, you can create new API key and API secret from the Security page. The API keys provide full access to the Yonyx resources owned by your account.
The following is an example of API key and API secret:
API Key (a 36-character, alphanumeric string). E.g.: f4389790-33ba-11e3-9459-bc764e10f0e8. API Secret (a 45-character string). E.g.: SGtuFbwOlsQTOlGuWZe2li4KvWh8y0XXvBbAZxbwL+Y=Your API Key identifies you as the party responsible for service requests. You include it in each request, so it’s not a secret.
Each API Key has an API Secret associated with it which is a secure text, please save it somewhere safe and accessible. For security reasons, you won’t be able to view it again.
Don’t e-mail API secret to anyone or expose it publicly. If you lose this API secret, you will need to generate a new API key and secret. No authorized person from Yonyx will ever ask for your API Secret.
When making API requests, the API secret should be included as a Bearer token in the request header.
Once the authentication header is set, the rest of the steps are straightforward.
Rate Limiting
🔗 Rate limits are divided into 5-minute intervals. You will be allowed to make 100 calls every 5 minutes. We limit API requests to a reasonable number in order to ensure that one customer’s use of Yonyx API does not adversely affect other customers. Without rate limiting, one customer could flood our system with requests in a way that would prevent another customer from being able to use the system. This happens sometimes when customers are first working with an API – a simple programming error could flood the API with requests that the customer doesn’t mean to send.
If you hit the rate limit, this is the body of the HTTP 429 (Too Many Requests) message that you will see. When you see this response, just retry your request after couple minutes.
{
error : [
{
code : 10006,
message : "Error Code: 10006 - Sorry, you've exceeded your limit of {x} requests in the last 5 minutes."
}
]
}Errors
🔗 Yonyx API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with Yonyx API servers.
HTTP STATUS CODE SUMMARY
200 OK - Everything worked as expected.
400 Bad Request - Often missing a required parameter.
401 Unauthorized - No valid API key was provided.
402 Request Failed - Parameters were valid but request failed.
404 Not Found - The requested item doesn't exist.
500, 502, 503, 504 Server errors - something went wrong on Yonyx API end.Deprecated Versions
Yonyx REST API version 2 is no longer actively maintained and support for version 2 will stop on December 31, 2024.
LOBs (Lines Of Business)
LOBs are the means through which Yonyx Guides are organized. Guides are published to an LOB targeting a specific Catalog. An LOB can contain multiple Catalogs and each Catalog can contain multiple Guides.
List LOBs
Returns a list of your lines of business. The lobs are returned sorted by creation date, with the most recently created lob appearing first.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/lobs/?key={API_KEY}'&lang=en \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of lobs. Each entry in the array is a separate lob object. If no lobs are available, the resulting array will be empty.
{
object : 'list',
count : 3,
data : [
{
object : 'lob',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Self Service'
},
{
object : 'lob',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Customer Service'
},
{...}
]
}Get LOB
Retrieves the details of an existing line of business (lob). You need to only supply the unique lob identifier.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
lob_id: (Required) The identifier of the lob to be retrieved.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/lobs/?key={API_KEY}&lob_id={lob_id}&lang=en' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns an lob object if a valid identifier was provided.
{
object : 'lob',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Self Service'
}Catalogs
Catalogs are the means through which Yonyx Guides are organized. Guides are published to a specific Catalog. A Catalog can contain multiple Guides.
List Catalogs
Returns a list of catalogs belonging to a particular line of business. The catalogs are returned sorted by creation date, with the most recently created catalog appearing first.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
lob_id: (Required) Line of business ID.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/catalogs/?key={API_KEY}&lob_id={lob_id}&lang=en' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of catalogs. Each entry in the array is a separate catalog object. If no catalogs are available, the resulting array will be empty. This request should never return an error.
{
object : 'list',
count : 5,
data : [
{
object : 'catalog',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Fix an Issue with Inkjet Printer',
guides : {
object : 'list',
count : 8,
data : [
{
object : 'guide',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Computer Cannot Find Printer or Will not Print',
updatedDate : 1452856689506
},
{
object : 'guide',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Print Head Errors on Inkjet Printers',
updatedDate : 1452856689300
},
{ ... },
{ ... }
]
}
},
{
object : 'catalog',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Customer Interactive HelpDesk',
guides : {
object : 'list',
count : 8,
data : [
{
object : 'guide',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Having Print Quality issues',
updatedDate : 1444856689506
},
{
object : 'guide',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Wireless Scanning issues',
updatedDate : 1451056689506
},
{ ... },
{ ... }
]
}
},
{ ... },
{ ... }
]
}Get Catalog
Retrieves the details of an existing catalog. You need to only supply the unique catalog identifier.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
catalog_id: (Required) The identifier of the catalog to be retrieved.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/catalogs/?key={API_KEY}&catalog_id={catalog_id}&lang=en' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a catalog object if a valid identifier was provided.
{
object : 'catalog',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Fix an Issue with Inkjet Printer',
guides : {
object : 'list',
count : 5,
data : [
{
object : 'guide',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Computer Cannot Find Printer or Will not Print',
updatedDate : 1444856689506
},
{
object : 'guide',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Print Head Errors on Inkjet Printers',
updatedDate : 1451056689506
},
{ ... },
{ ... }
]
}
}Guides
List Guides
Returns a list of root guidance steps (start point of an interactive guidance flow) belonging to a particular line of business. A max of 20 objects will be returned starting at index offset if provided.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
lob_id: (Required) Line of business ID.
offset: (Optional) Default is 0. An offset into the list of returned items. The API will return the number of items starting at that offset.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/guides/?key={API_KEY}&lob_id={lob_id}&offset=40&lang=en' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of guides, starting at index offset. Each entry in the array is a separate guide object. If no guides are available, the resulting array will be empty. This request should never return an error.
{
object : 'list',
count : 20,
next_offset : 26,
data : [
{
object : 'step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Handling "Windows Update Failed" Error Msg.',
match_fragment : '',
updatedDate : 1444856689506
},
{
object : 'step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'I need help for resolving Internet accessibility issue',
match_fragment : '',
updatedDate : 1444856689729
},
{ ... },
{ ... }
]
}
Keyword Search Guides
Returns a list of yonyx guidance steps matching the provided keyword(s). A max of 20 objects will be returned starting at index offset if provided.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
lob_id: (Required) Line of business ID. If this LOB is configured with Root-Only search, this request will search across all published roots.
query: (Required) Keywords that will be used to match. URL encode keywords. Eg. URL-Encode( "keyword1 keyword2's keyword3" ) should result in "keyword1+keyword2%27s+keyword3"
search_type: (Required) Search type. Valid values are 'keyword' or 'tag'
offset: (Optional) Default is 0. An offset into the list of returned items. The API will return the number of items starting at that offset.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/guides/?key={API_KEY}&lob_id={lob_id}&query=blue%20cash&search_type=keyword&lang=en' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of guides, starting at index offset. Each entry in the array is a separate guide object. If no guides are available, the resulting array will be empty. This request should never return an error.
{
object : 'list',
count : 20,
next_offset : 26,
data : [
{
object : 'step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Print Head Errors on Inkjet \u003cem\u003ePrinters\u003c/em\u003e',
match_fragment :
'You see an error message on your \u003cem\u003ePrinter\u003c/em\u003e\u0027s LCD panel. This message is typically related to either the Print head or the Cartridge. Let us guide you interactively to help resolve the \u003cem\u003eissue\u003c/em\u003e you are facing. ... What model \u003cem\u003eprinter\u003c/em\u003e do you need help with?',
updatedDate : 1444856689506
},
{
object : 'step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : '\u003cem\u003ePrinter\u003c/em\u003e is Printing Banner Page on every given Print Job',
match_fragment :
'This \u003cem\u003eissue\u003c/em\u003e is noticed if the banner Page option is selected in EWS (Embedded Web Server). To resolve this Problem: Go to EWS page using the \u003cem\u003eprinter\u003c/em\u003e IP address and then Go to Settings -\u003e General Settings -\u003e General Active Card Settings -\u003e Uncheck Banner Page and Submit Selection. ... Was the \u003cem\u003eissue\u003c/em\u003e resolved ?',
updatedDate : 1451056689506
},
{ ... },
{ .... }
]
}Tag Search Guides
Returns a list of yonyx guidance steps associated with the tag(s). A max of 20 objects will be returned starting at index offset if provided.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
lob_id: (Required) Line of business ID. If this LOB is configured with Root-Only search, this request will search across all published roots.
query: (Required) Tags that will be used to match. URL encode tags. Eg. URL-Encode( "printer page-setup" ) should result in "tag1+page-setup"
search_type: (Required) Search type. Valid values are 'keyword' or 'tag'
offset: (Optional) Default is 0. An offset into the list of returned items. The API will return the number of items starting at that offset.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/guides/?key={API_KEY}&lob_id={lob_id}&query=printer&search_type=tag&lang=en' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of guides, starting at index offset. Each entry in the array is a separate guide object. If no guides are available, the resulting array will be empty. This request should never return an error.
{
object : 'list',
count : 20,
next_offset : 26,
data : [
{
object : 'step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Print Head Errors on Inkjet \u003cem\u003ePrinters\u003c/em\u003e',
match_fragment : ' ... ',
updatedDate : 1451056689506
},
{
object : 'step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : '\u003cem\u003ePrinter\u003c/em\u003e is Printing Banner Page on every given Print Job',
match_fragment : ' ... ',
updatedDate : 1451056689234
},
{ ... },
{ ... }
]
}Traverse Guide
Retrieves the details of an existing guidance step.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
node_id: (Required) The identifier of the node. Can pass either a Guidance Step Id or a User Response Id.
Guidance Step Id is passed during the initial request of the traversal.
User Response Id is passed during subsequent requests of the traversal. This will fetch the next Guidance Step connected to this User Response.
user_email: (Required) The end user's email address (the user viewing this content).
user_type: (Required) The end user's type.
Pass "ext" for external user or "int" for the internal user.
Internal users are typically your agents/consultants/employees using this guide to help your customers either on the phone or on the field.
External users are typically your customers using this guide to self-help.
session: (Required) Session ensures that all the steps of this guide traversed by the user show up as a single incident under Analytics.
Pass "initial" for the initial request / first step of the guide.
For subsequent requests until the user exits out of the guide, pass the value of session property from the previous response.
Failing to pass this will result in a new incident per step.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
incident_id: (optional) When redirecting from one guide to another, this is the transcriptID of the guide that is redirecting to another guide. Passing this "Parent Incident Id" ensures that all placeholder values are handed over from the parent incident to the child incident.
reference_id: (optional) The Reference Id, typically your CRM or Service Desk incident Id. Pass rid when session = "initial".
EXAMPLE HTTP GET REQUEST
Initial request for a guide
curl --location 'https://developer.yonyx.com/y/apiv3/guides/traverse?key={API_KEY}&node_id={node_id}&user_email={user_email}&user_type={user_type}&session=initial&lang=en' \
--header 'Authorization: Bearer {API_SECRET}'
Subsequent request for the steps of the same guide
curl --location 'https://developer.yonyx.com/y/apiv3/guides/traverse?key={API_KEY}&node_id={node_id}&user_email={user_email}&user_type={user_type}&session={SESSION_FROM_PREVIOUS_RESPONSE}&lang=en' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a guidance family object if a valid identifier was provided.
=================================================
Example guidance family with command auto-traversal
Refer Get Command Auto Traversal to learn how to auto-traverse with a command's return value
=================================================
{
object : 'guidance_family',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Place T-Shirt Order',
body : 'Place an order for {{ph:t-shirt-clor}} t-shirt or {ph:t-shirt-size}} size .',
inquiry : 'Was the order placed?',
notes : '',
commandInternalName : 'place-order',
commandParameters : {
object : 'list',
count : 2,
data : [
{
name : 't-shirt-color',
value : 'Blue'
},
{
name : 't-shirt-size',
value : 'Small'
}
]
},
placeholders : {
object : 'list',
count : 2,
data : [ '{{ph:t-shirt-color}}', '{{ph:t-shirt-size}}' ]
},
placeholderValues : {
object : 'list',
count : 2,
data : [
{
name : 't-shirt-color',
value : 'Blue'
},
{
name : 't-shirt-size',
value : 'Small'
}
]
},
user_responses : {
object : 'list',
count : 2,
data : [
{
object : 'user_response',
id : 'a8d6f340-9d72-11e5-850c-bc764e10d166',
body : 'Order succeeded',
conditionGrouping : 'any',
conditions : {
object : 'list',
count : 2,
data : [
{
operator : 'equal-to',
operand : 'ordered'
},
{
operator : 'equal-to',
operand : 'ordered-with-discount'
}
]
},
placeholderValues : {
object : 'list',
count : 1,
data : [
{
name : 'order-status',
value : 'ordered'
}
]
},
updatedDate : 1452856689506
},
{
object : 'user_response',
id : 'a8d6f340-9d72-11e5-850c-bc764e10d166',
body : 'Order failed',
conditionGrouping : 'any',
conditions : {
object : 'list',
count : 2,
data : [
{
operator : 'equal-to',
operand : 'ordered-failed'
},
{
operator : 'equal-to',
operand : 'discount-not-applicable'
}
]
},
placeholderValues : {
object : 'list',
count : 1,
data : [
{
name : 'order-status',
value : 'failed'
}
]
},
updatedDate : 1452856689506
}
]
},
transcriptId : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
transcriptUrl : 'https://subdomain.yonyx.com/y/incident/?did=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
session : 'NBwSd2ytk2X%2FbjqA5h2BXsK....6kfAe8Wwa6MrOffPGedBSad2l',
rootId : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
form : {
object : 'list',
count : 3,
data : [
{
name : 'buyer-name',
type : 'String',
value : ''
},
{
name : 'claim-status',
type : 'String',
value : ''
},
{
name : 'claim-no',
type : 'String',
value : ''
}
]
},
formMarkup :
'<form class="yonyx-form" name="data-capture-3" action="#"><fieldset ><div class="form-group"><label>Name</label> <span class="glyphicon glyphicon-star-empty emphasize"></span><input class="form-control fld " type="input" name="buyer-name" maxlength="30" required="required" value="John Doe" ></div><div class="form-group"><label>Date</label> <span class="glyphicon glyphicon-star-empty emphasize"></span><input class="form-control fld " type="date" name="claim-status" min="2020-01-05" max="2020-01-10" required="required" value="2020-01-07" ></div><div class="form-group"><label>Number</label> <span class="glyphicon glyphicon-star-empty emphasize"></span><input class="form-control fld " type="number" name="claim-no" maxlength="30" min="5" max="15" required="required" value="7" ></div></fieldset></form>',
score : 0,
commandType : 'yonyx-command',
placeholderAutoTraverse : false,
placeholderAutoTraversalId : '',
redirectId : '',
redirectType : '',
returnToParent : false,
updatedDate : 1452856689506
}
=================================================
Example guidance family with placeholder auto-traversal
=================================================
{
object : 'guidance_family',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'T-Shirt Preference',
body : 'You have chosen {{ph:t-shirt-clor}} t-shirt of {ph:t-shirt-size}} size .',
inquiry : 'Do you want to proceed?',
notes : '',
commandInternalName : '',
commandParameters : {
object : 'list',
count : 0,
data : []
},
placeholders : {
object : 'list',
count : 2,
data : [ '{{ph:t-shirt-color}}', '{{ph:t-shirt-size}}' ]
},
placeholderValues : {
object : 'list',
count : 2,
data : [
{
name : 't-shirt-color',
value : 'Blue'
},
{
name : 't-shirt-size',
value : 'Small'
}
]
},
user_responses : {
object : 'list',
count : 2,
data : [
{
object : 'user_response',
id : 'a8d6f340-9d72-11e5-850c-bc764e10d166',
body : 'Modern',
conditionGrouping : 'all',
conditions : {
object : 'list',
count : 0,
data : []
},
placeholderConditionGrouping : 'all',
placeholderConditions : {
object : 'list',
count : 2,
data : [
{
leftOperand : 't-shirt-size',
operator : 'equal-to',
rightOperand : 'Small'
},
{
leftOperand : 't-shirt-color',
operator : 'equal-to',
rightOperand : 'Blue'
}
]
},
placeholderValues : {
object : 'list',
count : 1,
data : [
{
name : 'style-code',
value : 'modern'
}
]
},
updatedDate : 1452856689300
},
{
object : 'user_response',
id : 'a8d6f340-9d72-11e5-850c-bc764e10d166',
body : 'Traditional',
conditionGrouping : 'all',
conditions : {
object : 'list',
count : 0,
data : []
},
placeholderConditionGrouping : 'all',
placeholderConditions : {
object : 'list',
count : 2,
data : [
{
leftOperand : 't-shirt-size',
operator : 'equal-to',
rightOperand : 'Large'
},
{
leftOperand : 't-shirt-color',
operator : 'equal-to',
rightOperand : 'Red'
}
]
},
placeholderValues : {
object : 'list',
count : 1,
data : [
{
name : 'style-code',
value : 'traditional'
}
]
},
updatedDate : 1452856689300
}
]
},
transcriptId : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
transcriptUrl : 'https://subdomain.yonyx.com/y/incident/?did=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
session : 'NBwSd2ytk2X%2FbjqA5h2BX...a6MrOffPGedBSad2l',
rootId : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
form : {
object : 'list',
count : 3,
data : [
{
name : 'buyer-name',
type : 'String',
value : ''
},
{
name : 'claim-status',
type : 'String',
value : ''
},
{
name : 'claim-no',
type : 'String',
value : ''
}
]
},
formMarkup :
'<form class="yonyx-form" name="data-capture-3" action="#"><fieldset ><div class="form-group"><label>Name</label> <span class="glyphicon glyphicon-star-empty emphasize"></span><input class="form-control fld " type="input" name="buyer-name" maxlength="30" required="required" value="John Doe" ></div><div class="form-group"><label>Date</label> <span class="glyphicon glyphicon-star-empty emphasize"></span><input class="form-control fld " type="date" name="claim-status" min="2020-01-05" max="2020-01-10" required="required" value="2020-01-07" ></div><div class="form-group"><label>Number</label> <span class="glyphicon glyphicon-star-empty emphasize"></span><input class="form-control fld " type="number" name="claim-no" maxlength="30" min="5" max="15" required="required" value="7" ></div></fieldset></form>',
score : 0,
commandType : 'yonyx-command',
placeholderAutoTraverse : true,
placeholderAutoTraversalId : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
redirectId : '',
redirectType : '',
returnToParent : false,
updatedDate : 1452856689300
}
=================================================
INSTRUCTIONS ON HANDLING HANDOFF/RETURN AND PLACEHOLDER AUTO-TRAVERSAL
=================================================
=================================================
INITIAL REQUEST
session=initial
node_id=Node Id (later becomes parent Guide)
Don't set parent_incident_id
=================================================
Complete URL:
https://developer.yonyx.com/y/apiv3/guides/traverse
?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&node_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&user_email=some-user@your-domain.com
&user_type=int
&session=initial
&lang=en
=================================================
SUBSEQUENT REQUEST - REGULAR
session=session value from previous response
node_id=User Response ID
Don't set parent_incident_id
=================================================
Complete URL:
https://developer.yonyx.com/y/apiv3/guides/traverse
?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&node_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&user_email=some-user@your-domain.com
&user_type=int
&session=EDPn4HQp9C...
&lang=en
=================================================
HANDLING HANDOFF (REDIRECT) / RETURN
=================================================
----------------------------------------------
SUBSEQUENT REQUEST - REDIRECT TO CHILD GUIDE
----------------------------------------------
If previous Response contains non-empty redirectId and redirectType:
redirectId: "590d12f0-6855-11eb-a673-76421da31ef2"
redirectType: "guidance_family"
returnToParent: false
Set these parameters in the next request:
session=initial
node_id=Value of redirectId from previous response
parent_incident_id=Value of transcriptId from previous response
----------------------------------------------
Complete URL:
https://developer.yonyx.com/y/apiv3/guides/traverse
?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&node_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&user_email=some-user@your-domain.com
&user_type=int
&session=initial
&lang=en
&parent_incident_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
----------------------------------------------
After a few subsequent requests in child guide
----------------------------------------------
https://developer.yonyx.com/y/apiv3/guides/traverse...
https://developer.yonyx.com/y/apiv3/guides/traverse...
https://developer.yonyx.com/y/apiv3/guides/traverse...
...
...
...
----------------------------------------------
SUBSEQUENT REQUEST - RETURN TO THE PARENT GUIDE
----------------------------------------------
If previous Response contains returnToParent=true, then redirectId and session carry Parent Guide information :
redirectId: "4a9276a0-ccf1-11ec-a090-5254004d38b5" - Guidance Step Id from the Parent Incident (step that initiated handoff)
redirectType: "guidance_family"
returnToParent: true
session: "uEITnDqNg2..." - Parent Guide's session
Set these parameters in the next request:
session=Value of session from previous reponse
node_id=Value of redirectId from previous response
Don't set parent_incident_id
----------------------------------------------
Complete URL:
https://developer.yonyx.com/y/apiv3/guides/traverse
?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&node_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&user_email=some-user@your-domain.com
&user_type=int
&session=uEITnDqNg2...
&lang=en
----------------------------------------------
VALID REDIRECT TYPES
----------------------------------------------
lob, catalog, guidance_family, and url
=================================================
HANDLING PLACEHOLDER AUTO-TRAVERSAL
=================================================
If previous Response contains placeholderAutoTraverse=true:
placeholderAutoTraverse true
placeholderAutoTraversalId "2b948a70-ccfd-11ec-a090-5254004d38b5"
Set these parameters in the next request:
session=Value of session from previous response
node_id=Value of placeholderAutoTraversalId from previous response
----------------------------------------------
Complete URL:
https://developer.yonyx.com/y/apiv3/guides/traverse
?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&parent_incident_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&node_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&user_email=some-user@your-domain.com
&user_type=int
&session=uOPTnDqNg2...
&lang=enCommand Auto Traversal
In any given step, determine which User Response qualifies for Command auto-traversal by providing the Command’s return value.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
session: (Required) Get this value from the response of the previous "guidance_family" method call.
commandReturnValue: (Required) Return value of the Command. A command is typically code that you run and the result of that code is commandReturnValue.
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/guides/command_auto_traversal?key={API_KEY}&session={SESSION_FROM_PREVIOUS_RESPONSE}&command_return_value={COMMAND_RETURN_VALUE}' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE WITH A POSITIVE MATCH
{
commandAutoTraverse : true,
commandAutoTraversalId : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
message : ''
}
EXAMPLE RESPONSE WITH NO MATCH
{
commandAutoTraverse : false,
commandAutoTraversalId : ''
message : 'The Command return value you provided did not match any User Response conditions for auto-traversal.'
}Set Placeholder Values
Sets/Updates the current Incident with provided Placeholder Values.
HTTP METHOD: PUT
PARAMETERS
key: (Required) Your API key.
session: (Required) Get this value from the response of the previous "guidance_family" method call.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
BODY
placeholderValues: (Required) JSON Array of name-value objects.
Eg.:
{
"placeholder_values": [
{
"name": "name",
"value": "John Doe"
},
{
"name": "order-status",
"value": "Returned"
}
]
}
EXAMPLE HTTP PUT REQUEST
curl --location --request PUT 'https://developer.yonyx.com/y/apiv3/guides/set_placeholder_values?key={API_KEY}&session={SESSION_FROM_PREVIOUS_RESPONSE}&lang=en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {API_SECRET}' \
--data '{
"placeholder_values": [
{
"name": "name",
"value": "John Doe"
},
{
"name": "order-status",
"value": "Returned"
}
]
}'
EXAMPLE RESPONSE
Returns a success message.
{
message : 'Set incident placeholder values succeeded.'
}Set Form Values
This method does the following:
1. Validates the form values. Returns error message if field validation fails.
2. Updates the current incident with provided Form values as Placeholder values.
HTTP METHOD: PUT
PARAMETERS
key: (Required) Your API key.
session: (Required) Get this value from the response of the previous "guidance_family" method call.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
BODY
formValues: (Required) JSON Array of name-value objects.
Eg.:
{
"form_values": [
{
"name": "buyer-name",
"value": "John Doe"
},
{
"name": "user-email",
"value": "user@email.com"
},
{
"name": "purchase-date",
"value": "2020-01-17"
},
{
"name": "purchase-time",
"value": "10:00"
},
{
"name": "order-status",
"value": "Returned"
}
]
}
EXAMPLE HTTP PUT REQUEST
curl --location --request PUT 'https://developer.yonyx.com/y/apiv3/guides/set_form_values?key={API_KEY}&session={SESSION_FROM_PREVIOUS_RESPONSE}&lang=en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {API_SECRET}' \
--data-raw '{
"form_values": [
{
"name": "buyer-name",
"value": "John Doe"
},
{
"name": "user-email",
"value": "user@email.com"
},
{
"name": "purchase-date",
"value": "2020-01-17"
},
{
"name": "purchase-time",
"value": "10:00"
},
{
"name": "order-status",
"value": "Returned"
}
]
}'
EXAMPLE RESPONSE
Returns a success message.
{
message : 'Set form values succeeded.'
}Create Feedback
Creates a feedback within an active traversal of a guide. This method can only be called during a live traversal.
HTTP METHOD: PUT
PARAMETERS
key: (Required) Your API key.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
session: (Required) Get this value from the response of the previous "guidance_family" method call.
Create Feedback can also be called without passing session in which case, "step_id", "incident_id", and "user_email") become mandatory required and you can skip session.
step_id: (Required) ID of the current step.
incident_id: (Required) ID of the current Incident (Transcript).
user_email: (Required) The user's email address (the user viewing this content).
BODY:
feedback: (Required) Feedback text not more than 5000 chars long.
Eg.
{
"feedback": "The screenshot in this step is inacurate. Please update it with the latest."
}
EXAMPLE HTTP PUT REQUEST
curl --location --request PUT 'https://developer.yonyx.com/y/apiv3/guides/create_feedback?key={API_KEY}&session={SESSION_FROM_PREVIOUS_RESPONSE}&step_id={step_id}&incident_id={incident_id}&user_email={user_email}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {API_SECRET}' \
--data '{
"feedback": "The screenshot in this step is inacurate. Please update it with the latest."
}'
EXAMPLE RESPONSE
Returns a success message.
{
message : 'Feedback created successfully.'
}Create Compliment
Creates a compliment within an active traversal of a guide. This method can only be called during a live traversal.
HTTP METHOD: PUT
PARAMETERS
key: (Required) Your API key.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
session: (Required) Get this value from the response of the previous "guidance_family" method call.
Create Compliment can also be called without passing session in which case, "step_id", "incident_id", and "user_email") become mandatory required and you can skip session.
step_id: (Required) ID of the current step.
incident_id: (Required) ID of the current Incident (Transcript).
user_email: (Required) The user's email address (the user viewing this content).
BODY:
compliment: (Required) Compliment text not more than 5000 chars long.
Eg.
{
"compliment": "These steps helped resolve my issues. Very helpful."
}
EXAMPLE HTTP PUT REQUEST
curl --location --request PUT 'https://developer.yonyx.com/y/apiv3/guides/create_compliment?key={API_KEY}&session={SESSION_FROM_PREVIOUS_RESPONSE}&step_id={step_id}&incident_id={incident_id}&user_email={user_email}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {API_SECRET}' \
--data '{
"compliment": "These steps helped resolve my issues. Very helpful."
}'
EXAMPLE RESPONSE
Returns a success message.
{
message : 'Compliment created successfully.'
}Incidents
List Incidents
Returns a list of Transcripts since the offset. A max of 10 transcripts will be returned starting at the offset provided. The transcripts are returned sorted by creation date, with the most recently created Transcript appearing first.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
lob_id: (Required) Line of business ID.
offset: (Required) An offset into the list of returned items. The API will return the number of items starting at that offset.
Offset accepts 2 types of values:
- Initial Request: The date since when to retrieve the list of Incidents/Transcripts, specified as the number of milliseconds since the epoch (00:00:00 UTC on January 1, 1970). Eg. 1672531200000 for 2023-Jan-01
- Subsequent Requests: The next_offset from the response of the previous API request. The value of next_offset is nothing but a Incident/Transcript ID. Eg. 99988830-047c-11e4-9638-bc764e10f0e8
endDate: (Required) End of the date range in UTC milliseconds format. Eg. 1672876800000 for 2023-Jan-05
EXAMPLE HTTP GET REQUEST
Let’s say you are trying to retrieve data for 2024-Jul-24, the requests and responses would look like this:
First request:
==============
offset: 1721865600000 (UTC milliseconds format of 2024-Jul-25 00:00:00)
endDate: 1721779200000 (UTC milliseconds format of 2024-Jul-24 00:00:00)
Remember, the data is returned in reverse chronological order. Think of offset as start date in reverse chronological order.
This is the reason 25-Jul-2024 has become start date and 24-Jul-2024 the end date.
curl --location 'https://developer.yonyx.com/y/apiv3/incidents/?key={API_KEY}&lob_id={lob_id}&offset=1721865600000&end_date=1721779200000' \
--header 'Authorization: Bearer {API_SECRET}'
First response:
===============
{
object : 'list',
count : 10,
next_offset : 'c6bee1b0-xxxx-xxxx-87df-46894e2acb2b',
data : [{…}]
...
}
Second request:
===============
offset: c6bee1b0-bb59-11e5-87df-46894e2acb2b (value of “next_offset” from the previous response. Notice how offset changed from milliseconds to GUID)
endDate: 1721779200000 (UTC milliseconds format of 2024-Jul-24 00:00:00)
curl --location 'https://developer.yonyx.com/y/apiv3/incidents/?key={API_KEY}&lob_id={lob_id}&offset=c6bee1b0-xxxx-xxxx-87df-46894e2acb2b&end_date=1721779200000' \
--header 'Authorization: Bearer {API_SECRET}'
Second response:
================
{
object : 'list',
count : 10,
next_offset : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
data : [{…}]
...
}
Third request and response
And so on.. until you hit the response with empty/null next_offset.
If the batch polling code is interrupted midway, you can start the next request from the previous “next_offset”.
So you will have to store the next_offset after every successful fetch.
Design the polling code to wake up, fetch the first batch of incidents, then enter a short sleep interval. After the interval, wake up again, fetch the next batch, and continue this cycle.
EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of Transcripts, starting at provided offset. If no Transcripts are available, the resulting array will be empty. This request should never return an error.
{
object : 'list',
count : 10,
next_offset : 'c6bee1b0-bb59-11e5-87df-46894e2acb2b',
data : [
{
object : 'transcript',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
referenceId : 'xxxxxxxx',
url : 'https://subdomain.yonyx.com/y/incident/?did\u003dxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
steps : {
object : 'list',
count : 3,
data : [
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'My TV Doesn\u0027t work',
question : 'Is your TV plugged into the wall socket?',
duration : '00:00:06'
},
{
object : 'transcript_step',
type : 'user_response',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'No it is not.'
},
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Plug it in',
question : 'Do you now see the red light come on?',
duration : '00:18:55'
}
]
},
summary :
'\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:06] My TV Doesn\u0027t work\nQ: Is your TV plugged into the wall socket?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:18:55] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------',
ownerName : 'user1',
ownerEmail : 'user1@company.com',
startTime : 1452855652483,
endTime : 1452856659750,
done : true,
doneDate : 1452856650050,
score : 0,
parentId : '',
groupId : '',
formattedStartTime : '2021-03-02 02:14:26',
formattedEndTime : '2021-03-02 02:14:56'
},
{
object : 'transcript',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
referenceId : 'xxxxxxxx',
url : 'https://subdomain.yonyx.com/y/incident/?did\u003dxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
steps : {
object : 'list',
count : 5,
data : [
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'My TV Doesn\u0027t work',
question : 'Is your TV plugged into the wall socket?',
duration : '00:00:06'
},
{
object : 'transcript_step',
type : 'user_response',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'No it is not.'
},
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Plug it in',
question : 'Do you now see the red light come on?',
duration : '00:18:55'
},
{
object : 'transcript_step',
type : 'user_response',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'No it is not.'
},
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Plug it in',
question : 'Do you now see the red light come on?',
duration : '00:00:02'
}
]
},
summary :
'\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:06] My TV Doesn\u0027t work\nQ: Is your TV plugged into the wall socket?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:18:55] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:00:02] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------',
ownerName : 'user1',
ownerEmail : 'user1@company.com',
startTime : 1452855652483,
endTime : 1452856659750,
done : true,
doneDate : 1452856650050,
score : 0,
parentId : '',
groupId : '',
formattedStartTime : '2021-03-01 01:00:00',
formattedEndTime : '2021-03-01 01:14:56'
},
{...},
{...},
{...}
]
}List Incidents by Reference Id
Returns a list of all Transcripts associated with the Reference Id provided. The Transcripts are returned sorted by creation date, with the most recently created Transcript appearing first.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
reference_id: (Required) The Reference Id, typically your CRM or Service Desk incident Id.
offset: (optional) An offset into the list of returned items. The API will return the number of items starting at the offset.
Offset accepts the next_offset from the response of the previous API request. The value of next_offset is nothing but a Transcript ID. Eg. 99988830-047c-11e4-9638-bc764e10f0e8
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/incidents/?key={API_KEY}&reference_id={reference_id}' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of Transcripts. Each entry in the array is a separate Transcript object. If no Transcripts are available, the resulting array will be empty. The startTime and endTime are in UTC time. You will need to convert them to desired timezone
{
object : 'list',
count : 2,
next_offset : 'c6bee1b0-bb59-11e5-87df-46894e2acb2b',
data : [
{
object : 'transcript',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
referenceId : 'xxxxxxxx',
url : 'https://subdomain.yonyx.com/y/incident/?did\u003dxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
steps : {
object : 'list',
count : 3,
data : [
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'My TV Doesn\u0027t work',
question : 'Is your TV plugged into the wall socket?',
duration : '00:00:06'
},
{
object : 'transcript_step',
type : 'user_response',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'No it is not.'
},
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Plug it in',
question : 'Do you now see the red light come on?',
duration : '00:18:55'
}
]
},
summary :
'\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:06] My TV Doesn\u0027t work\nQ: Is your TV plugged into the wall socket?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:18:55] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------',
ownerName : 'user1',
ownerEmail : 'user1@company.com',
startTime : 1452855652483,
endTime : 1452856659750,
done : true,
doneDate : 1452856650050,
score : 0,
parentId : '',
groupId : '',
formattedStartTime : '2021-03-02 02:14:26',
formattedEndTime : '2021-03-02 02:14:56'
},
{
object : 'transcript',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
referenceId : 'xxxxxxxx',
url : 'https://subdomain.yonyx.com/y/incident/?did\u003dxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
steps : {
object : 'list',
count : 5,
data : [
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'My TV Doesn\u0027t work',
question : 'Is your TV plugged into the wall socket?',
duration : '00:00:06'
},
{
object : 'transcript_step',
type : 'user_response',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'No it is not.'
},
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Plug it in',
question : 'Do you now see the red light come on?',
duration : '00:18:55'
},
{
object : 'transcript_step',
type : 'user_response',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'No it is not.'
},
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Plug it in',
question : 'Do you now see the red light come on?',
duration : '00:00:02'
}
]
},
summary :
'\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:06] My TV Doesn\u0027t work\nQ: Is your TV plugged into the wall socket?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:18:55] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:00:02] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------',
ownerName : 'user1',
ownerEmail : 'user1@company.com',
startTime : 1452855652483,
endTime : 1452856659750,
done : true,
doneDate : 1452856650050,
score : 0,
parentId : '',
groupId : '',
formattedStartTime : '2021-03-02 01:11:06',
formattedEndTime : '2021-03-02 01:15:00'
}
]
}Get Incident
Retrieves the details of an existing transcript. You need to only supply the unique Transcript Id. The startTime and endTime are in UTC time. You will need to convert them to desired timezone.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
incident_id: (Required) The identifier of the Incident/Transcript to be retrieved.
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/incidents/?key={API_KEY}&incident_id=31b41a30-xxxx-xxxx-xxxx-d63771a0ecea' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a Transcript object if a valid identifier was provided.
{
object : 'transcript',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
url : 'https://subdomain.yonyx.com/y/incident/?did\u003dxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
steps : {
object : 'list',
count : 5,
data : [
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'T-Shirt color',
question : 'What is your favorite color?',
duration : '00:00:06'
},
{
object : 'transcript_step',
type : 'user_response',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Blue.',
placeholderValues : {
object : 'list',
count : 2,
data : [
{
name : 't-shirt-color',
value : 'Blue'
}
]
}
},
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'T-Shirt size',
question : 'What is your T-Shirt size?',
duration : '00:00:55'
},
{
object : 'transcript_step',
type : 'user_response',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Small.',
placeholderValues : {
object : 'list',
count : 2,
data : [
{
name : 't-shirt-size',
value : 'Small'
}
]
}
},
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Place Order',
question : 'Do you wish to proceed with placing the order?',
duration : '00:01:02'
}
]
},
summary :
'\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:06] T-Shirt color\nQ: What is your favorite color?\n--------------------------------------------\nU: Blue.\n--------------------------------------------\nT: [00:00:55] T-Shirt size\nQ: What is your T-Shirt size?\n--------------------------------------------\nU: Small.\n--------------------------------------------\nT: [00:01:02] Place Order\nQ: Do you wish to proceed with placing the order?\n--------------------------------------------',
ownerName : 'user1',
ownerEmail : 'user1@company.com',
startTime : 1452855652483,
endTime : 1452856659750,
done : true,
doneDate : 1452856650050,
score : 0,
parentId : '',
groupId : '',
formattedStartTime : '2021-03-02 02:14:26',
formattedEndTime : '2021-03-02 02:14:56'
}Associate Reference Id
🔗 Associates Reference ID (typically your CRM or Service Desk incident Id) with multiple existing Incidents/Transcripts (up to 10).
HTTP METHOD: PUT
PARAMETERS
key: (Required) Your API key.
reference_id: (Required) The Reference Id, typically your CRM or Service Desk incident Id.
incident_ids: (Required) Incident/Transcript Ids up to 10. These are Yonyx incident Ids.
EXAMPLE HTTP PUT REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/incidents/associate_reference_id?key={API_KEY}&reference_id={reference_id}&incident_ids={COMMA_SEPARATED_INCIDENT_IDS}' \
--header 'Authorization: Bearer Kla3wPAqsonBNqyYVnIx2KrLUcf7QeLhSed6txy4RSE='
EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of Transcript objects. If no Transcript object is available, the resulting array will be empty. This request should never return an error.
{
object : 'list',
count : 4,
data : [
{ object : 'transcript', ...},
{ object : 'transcript', ...},
{...},
{...}
]
}Users
List Users
Returns a list of Users since the offset. A max of 20 users will be returned starting at the offset provided.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
offset: (optional) An offset into the list of returned items. The API will return the number of items starting at the offset.
Offset accepts the next_offset from the response of the previous API request. The value of next_offset is nothing but a User ID. Eg. 99988830-xxxx-xxxx-xxxx-bc764e10f0e8.
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/users/?key={API_KEY}' \
--header 'Authorization: Bearer {API_SECRENT}'
EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of Users, starting at provided offset. If no Users are available, the resulting array will be empty.
{
"object": "list",
"count": 20,
"next_offset": 20,
"data": [
{
"object": "user",
"id": "15xxxx10-xxxx-xxxx-xxxx-4040xxxx2aa1",
"name": "User Full Name",
"email": "user-email@email.com",
"is_author": false,
"is_internal": true,
"is_disabled": false,
"is_admin": false,
"created": 1319312595393,
"created_formatted": "2011-10-22 12:43:15"
},
{
"object": "user",
"id": "xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxx",
"name": "User2 Full Name",
"email": "user2@gmail.com",
"is_author": false,
"is_internal": false,
"is_disabled": false,
"is_admin": false,
"created": 1327124302838,
"created_formatted": "2012-01-20 21:38:22"
},
{ ... },
{ ... },
{ ... },
]
}Get User by Id
Retrieves the details of an existing user. You need to only supply the unique User Id.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
user_id: (Required) ID of the User.
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/users/?key={API_KEY}&user_id={user_id}' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of single User.
{
"object": "list",
"count": 1,
"data": [
{
"object": "user",
"id": "15xxxx10-xxxx-xxxx-xxxx-4040xxxx2aa1",
"name": "User Full Name",
"email": "user-email@email.com",
"is_author": false,
"is_internal": true,
"is_disabled": false,
"is_admin": false,
"created": 1319312595393,
"created_formatted": "2011-10-22 12:43:15"
}
]
}Get User by Email
Retrieves the details of an existing user. You need to only supply the unique User Email.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
user_email: (Required) Email of the User.
EXAMPLE HTTP GET REQUEST
curl --location 'https://developer.yonyx.com/y/apiv3/users/?key={API_KEY}&user_email={user_email}' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of single User.
{
"object": "list",
"count": 1,
"data": [
{
"object": "user",
"id": "15xxxx10-xxxx-xxxx-xxxx-4040xxxx2aa1",
"name": "User Full Name",
"email": "user-email@email.com",
"is_author": false,
"is_internal": true,
"is_disabled": false,
"is_admin": false,
"created": 1319312595393,
"created_formatted": "2011-10-22 12:43:15"
}
]
}Enable User
Enable a disabled user.
HTTP METHOD: PUT
PARAMETERS
key: (Required) Your API key.
user_email: (Required) The email address of the user you want to enable.
EXAMPLE HTTP PUT REQUEST
curl --location --request PUT 'https://developer.yonyx.com/y/apiv3/users/enable_user?key={API_KEY}&user_email={user_email}' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a success message.
{
message : 'User enabled successfully.'
}Disable User
Disable an active user.
HTTP METHOD: PUT
PARAMETERS
key: (Required) Your API key.
user_email: (Required) The email address of the user you want to enable.
EXAMPLE HTTP PUT REQUEST
curl --location --request PUT 'https://developer.yonyx.com/y/apiv3/users/disable_user?key={API_KEY}&user_email={user_email}' \
--header 'Authorization: Bearer {API_SECRET}'
EXAMPLE RESPONSE
Returns a success message.
{
message : 'User disabled successfully.'
}