Interactions API
Overview¶
Interaction Designer interactions API provides access to list of interactions and details of individual interactions.
List of interactions¶
With this endpoint you are able to get list of all interactions that you have access to.
Endpoint:
1 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 |
|
Request parameters¶
Parameter | Type | Required | Description |
---|---|---|---|
collection_id |
integer | optional | Set to a collection_id parameter to return interactions only from given collection. |
ordering |
name | created_at | updated_at |
optional | Set to a ordering parameter to return interactions based on specific order. If you pass the name type, list of interactions is sorted alphabetically. If created_at is set, list of interactions is sorted based on created date.Similarly, setting updated_at sorts the list of interactions based on its modified date. To sort the list of interactions in a reverse order, you can use the same ordering type with - before them like -name , -created_at or -updated_at . |
Example:
1 |
|
Response¶
Response is a list of following resources.
Attribute | Type | Description |
---|---|---|
id |
string | Interaction ID |
legacy_id |
integer | This is a legacy Interaction ID which is deprecated. This will be remove in future |
collection_id |
integer | ID of the collection this interaction belongs to |
organization_id |
string | ID of the interaction owner organization |
created_at |
string | Time string when the interaction was created in ISO-8601 format, eg. "2021-02-18T10:10:57.242Z" |
name |
string | Name of the interaction |
notes |
string | Interaction description or notes text |
author_company_id |
string | ID string of the interaction creator organization |
author_user_id |
string | ID string of the user who created this interaction |
published_asset_id |
string | Deprecated, do not use! |
published_at |
string | Time string when the interaction was last time published in ISO-8601 format, eg. "2021-02-18T10:10:57". Can be null if the interaction is not yet published |
published_name |
string | Name of the published interaction. Can be null if the interaction is not yet published |
theme_id |
integer | ID of the theme object used |
updated_at |
string | Time string when the interaction was last updated in ISO-8601 format, eg. "2021-02-18T10:10:57.242Z" |
updated_by_user_company_id |
string | ID string of the organization which updated the interaction |
updated_by_user_id |
string | ID string of the user who updated the interaction |
Get single interaction¶
With this endpoint you are able to get specific interaction from the list of interactions.
Endpoint:
1 |
|
Example:
1 |
|
Response¶
Response is a list of following resources.
Attribute | Type | Description |
---|---|---|
id |
string | Interaction ID |
legacy_id |
integer | This is a legacy Interaction ID which is deprecated. This will be remove in future |
collection_id |
integer | ID of the collection this interaction belongs to |
organization_id |
string | ID of the interaction owner organization |
created_at |
string | Time string when the interaction was created in ISO-8601 format, eg. "2021-02-18T10:10:57.242Z" |
name |
string | Name of the interaction |
notes |
string | Interaction description or notes text |
author_company_id |
string | ID string of the interaction creator organization |
author_user_id |
string | ID string of the user who created this interaction |
draft_data |
object | Object that contains all internal data of interaction |
draft_data_version |
integer | Version of the interaction |
preview_canvas_rotated |
boolean | If preview canvas is rotated to portrait mode |
preview_canvas_size_type |
string | Describes which preview canvas type was selected previously. One of "mobile1", "mobile2", "desktop1", "desktop2" |
editor_canvas_size_type |
string | Describes which editor canvas type was selected previously. One of "mobile1", "mobile2", "desktop1", "desktop2" |
preview_url |
string | Previously used URL to preview the interaction, can be null if preview url is not set |
published_asset_id |
string | Deprecated, do not use! |
published_at |
string | Time string when the interaction was last time published in ISO-8601 format, eg. "2021-02-18T10:10:57". Can be null if the interaction is not yet published |
published_data_version |
integer | Version of the published interaction |
published_name |
string | Name of the published interaction. Can be null if the interaction is not yet published |
theme_id |
integer | ID of the theme object used |
updated_at |
string | Time string when the interaction was last updated in ISO-8601 format, eg. "2021-02-18T10:10:57.242Z" |
updated_by_user_company_id |
string | ID string of the organization which updated the interaction |
updated_by_user_id |
string | ID string of the user who updated the interaction |
flow_mode |
object | Object contains flowmode data if flowmode is used. Can be null if interaction is not yet using flowMode |
Update a single interaction¶
With this endpoint you are able to update existing interaction.
Endpoint:
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
Response¶
Attribute | Type | Description |
---|---|---|
uid |
integer | Interaction integer ID |
name |
string | Name of the interaction |
notes |
string | Interaction description or notes text |
organizationUid |
string | UUID string of the interaction owner organization |
workspaceUid |
integer | ID of the collection this interaction belongs to |
creatorUserId |
string | UUID string of the user whom created this interaction |
creatorUserOrganizationUid |
string | UUID string of the interaction creator organization. |
createdDate |
date/time | Time when the interaction was created in ISO-8601 format, eg. 2021-02-18T10:10:57.242Z |
updatedDate |
date/time | Time when the interaction was last updated in ISO-8601 format, eg. 2021-02-18T10:10:57.242Z |
updatedUserId |
string | UUID string of the user who last updated the interaction |
updatedUserOrganizationUid |
string | UUID string of the interaction updater organization. |
themeId |
integer | ID of the theme object used |
templateName |
string | Name of the template used in this interaction, can be null if no template used. |
publishedAssetUid |
string | Deprecated, do not use! |
publishedDate |
date/time | Time when the interaction was last time published in ISO-8601 format, eg. 2021-02-18T10:10:57 . Can be null if the interaction was not yet published. |
isPublished |
boolean | Is the interaction published. |
interactionUuid |
string | UUID of the interaction. This is used to identify interaction in many API's |
tag |
date/time | Tag timestamp of interaction. This is used internally to track versions and make sure that multiple users don't override each others changes when saving. |
project |
object | Interaction definition. |
jsonVersion |
integer | Giosg internal version of the interaction definition JSON. |
editorCanvasSizeType |
string | Describes which editor canvas type was selected previously. One of "mobile1" , "mobile2" , "desktop1" , "desktop2" . |
previewUrl |
string | Previously used URL to preview the interaction, can be null if preview url is not set. |
previewCanvasSizeType |
string | Describes which preview canvas type was selected previously. One of "mobile1" , "mobile2" , "desktop1" , "desktop2" . |
previewCanvasRotated |
boolean | If preview canvas is rotated to portrait mode. |
Delete interaction¶
With this endpoint it is possible to delete an interaction.
Endpoint:
1 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
API will respond with HTTP 200 OK
if deletion was succesfull.
Copy an interaction¶
With this endpoint it is possible to copy an interaction to same or to some other collection.
Endpoint:
1 |
|
Example:
1 |
|
Response¶
If the copying is successful, API will respond with the same data that would be available from Get single interaction API endpoint.
Move an interaction¶
With this endpoint it is possible to move an interaction to same or to some other collection within same organization.
Endpoint:
1 |
|
Example:
1 |
|
Response¶
If the moving is successful, API will respond with the same data that would be available from Get single interaction API endpoint.
Create a new interaction¶
With this endpoint you are able to create a new interaction. Creating a new interaction requires complex payload so it is highly recommended to fetch Interaction templates first and use one of those as payload.
If you want to create an empty interaction with this API, it is easiest to first fetch initial request payload using Interaction default project template API. It is recommended to always fetch default project for a base for the payload as the initial project payload may change over time.
Response of that endpoint then can be modified as user likes. API user also needs to add Collection ID to workspaceUid
attribute and Theme ID to themeId
attribute in order for the request to be successful.
Endpoint:
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
|
Request parameters¶
Parameter | Type | Required | Description |
---|---|---|---|
name |
string | Required | Name of the interaction to create |
editorCanvasSizeType |
string | Required | Describes which editor canvas type should be set as default for interactions created using this template. One of "mobile1" , "mobile2" , "desktop1" , "desktop2" . |
jsonVersion |
integer | Required | Giosg internal version of the interaction template definition JSON. |
templateName |
string | Required | Name of the template that was used. |
themeId |
integer | Optional | ID of the theme object to be used. If no id is provided, then we'll use any theme we'll find in the collection or create a default theme if collection has no themes. |
workspaceUid |
integer | Required | ID of the collection this interaction should be placed to |
project |
object | Required | Interaction JSON definition. |
Response¶
If creation of interaction was successful, API will respond with same data that would be available from Get single interaction API endpoint.
Publish a interaction¶
With this endpoint you are able to publish interaction.
Publishing interaction always publishes latest version of interaction. For this reason there is optional query parameter called tag
that can be used to prevent accidentally publishing other users changes.
Tag is basically a value from projects updatedDate
field and when this value is provided, interaction will not be published if this value has changed. This is used to prevent accidentally publishing changes that other users may have made to interaction at the same time.
Endpoint:
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
Response¶
If the publishing is successful, the API will respond with the same data that would be available from the Get single interaction API endpoint.
If the tag
parameter was used and the publishing fails because to interaction was changed, the API will respond with null
.
Request parameters¶
Parameter | Type | Required | Description |
---|---|---|---|
tag |
string | optional | Tag to publish. If this is omitted, then latest interaction version is published without any additional checks. Tag is same as interactions last updated at time from updatedDate field. |
Unpublish a interaction¶
With this endpoint you are able to unpublish an interaction. This won't delete any rules that might have been setup to show the interaction, but does prevent the interaction to be loaded by the rules.
Unpublishing an interaction will always unpublish the latest published version of an interaction. For this reason there is optional query parameter called tag
that can be used to prevent accidentally unpublishing version that other user has published simultaneously.
Tag is basically a value from projects updatedDate
field and when this value is provided, interaction will not be unpublished if this value has changed.
Endpoint:
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
Response¶
If the unpublishing is successful, the API will respond with the same data that would be available from the Get single interaction API endpoint.
If the tag
parameter was used and the unpublishing fails because to interaction was changed, the API will respond with null
.
Request parameters¶
Parameter | Type | Required | Description |
---|---|---|---|
tag |
string | optional | Tag to unpublish. If this is omitted, then latest published version of interaction gets unpublished without any additional checks. Tag is same as interactions last updated at time from updatedDate field. |
Revert an interaction to previously published state¶
With this endpoint you are able to revert the changes of an interaction to the previously published state. Reverting is not possible if the interaction has not been published yet.
Reverting interaction always reverts it to latest published version of interaction.
Endpoint:
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 |
|
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Response¶
If the reverting is successful, the API will respond with the same data that would be available from the Get single interaction API endpoint.
Note that if interaction has not been published yet, API will respond with HTTP 400 Bad Request
as there isn't a version to revert to.
Interaction publish log¶
With this endpoint you are able to list the published history of a specific interactions.
Endpoint:
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
Response¶
Attribute | Type | Description |
---|---|---|
interactionPublishedLogItemUid |
string | UUID of log item |
publishedName |
string | Name of the interaction at the time of publishing |
interactionUid |
string | UUID of interaction |
orgId |
string | UUID of the organization |
publishedJsonVersion |
integer | JSON version at the time of publishing |
publishedByUserId |
string | UUID string of the user who published the interaction |
publishedDate |
date/time | Time when the interaction was published in ISO-8601 format, eg. 2021-02-18T10:10:57.242Z |
publishedProject |
object | Full JSON representation of the interaction |
Interaction templates¶
With this endpoint you are able to list interaction templates. Templates can help you while creating a new interaction. It is recommended to use templates with the Create a new interaction API to make it easier to build the correct payload.
Endpoint:
1 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 |
|
Response¶
Response will be a array of following resources.
Attribute | Type | Description |
---|---|---|
uid |
integer | Integer ID of the template |
name |
string | Name of the interaction template |
notes |
string | Notes or description |
organizationUid |
string | UUID string of the organization |
creatorUserId |
string | UUID string of the user who created this interaction template |
creatorUserOrganizationUid |
string | UUID string of the organization where creatorUserId belongs to |
createdDate |
date/time | Time when the interaction template was created in ISO-8601 format, eg. 2021-02-18T10:10:57.242Z |
updatedDate |
date/time | Time when the interaction template was last updated in ISO-8601 format, eg. 2021-02-18T10:10:57.242Z |
updatedUserId |
string | UUID string of the user who last updated the interaction template |
updatedUserOrganizationUid |
string | UUID string of the interaction template updater organization. |
themeId |
integer | ID of the theme object used |
templateName |
string | Name of the template used, null always for template interactions. |
publishedAssetUid |
string | Deprecated, do not use! |
publishedDate |
date/time | Time when the interaction template was published in ISO-8601 format, eg. 2021-02-18T10:10:57.242Z |
isPublished |
boolean | Is the interaction template published. |
interactionUuid |
string | UUID of the interaction template. This is used to identify interaction in many API's |
tag |
date/time | Tag timestamp of interaction template. This is used internally to track versions and make sure that multiple users don't override each others changes when saving. |
project |
object | Interaction template definition. This is the payload that can be used to create new interaction from. |
jsonVersion |
integer | Giosg internal version of the interaction template definition JSON. |
editorCanvasSizeType |
string | Describes which editor canvas type should be set as default for interactions created using this template. One of "mobile1" , "mobile2" , "desktop1" , "desktop2" . |
previewUrl |
string | Preview url is null for interaction templates |
previewCanvasSizeType |
string | Preview canvas type is null for interaction templates |
previewCanvasRotated |
boolean | false for interaction templates |
workspaceUid |
integer | ID of the collection this interaction template belongs to |
Interaction default project template¶
With this endpoint you are able to get default interaction project template. This can be used to create a new interactions with the Create a new interaction API.
This is different from a template since a template is already filled with a basic layout, while this endpoint will return an empty interaction.
Endpoint:
1 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 |
|
Response¶
Response will be a object with following attributes:
Attribute | Type | Description |
---|---|---|
name |
string | Name of the interaction template |
templateName |
string | Name of the template used, null always for template interactions. |
project |
object | Interaction template definition. This is the payload that can be used to create new interaction from. |
jsonVersion |
integer | Giosg internal version of the interaction template definition JSON. |
editorCanvasSizeType |
string | Describes which editor canvas type should be set as default for interactions created using this template. One of "mobile1" , "mobile2" , "desktop1" , "desktop2" . |