Payloads

This page describes the payloads which will be send, in the messages, to the Service. We also explain when this message is triggered.

There are 4 different payload structures:

one for Events
one for Actions
one for Messages (similar to Events)
one for Client merging

Event

These are events that the Client can trigger.

Property name	Data type	Description
type	`String`	Determines what kind of information the payload provides. In this case it will always be `event`.
body	`Object`	Contains information about the current event, and the Parley account.
body.name	`String`	Contains the name of the current event.
body.body	`Object`	Contains information specific to the event.
body.user	`Object`	Contains information about the current user.
body.user.id	`Integer`	Contains the numeric identifier of the current user.
body.user.uniqueIdentifier	`String`\|`null`	Represents the extern Id which was given to the user when the user logged in. This could be for example a customer id. For more information, see User Registration
body.user.additionalInformation	`Object`\|`null`	Contains custom information for the current user. For more information, see the POST /devices api call or one for Events - one https://developers.parley.nu/docs/settings#general for the web library setting.

Start typing

This is triggered when the user is typing a message in the Parley chat window.
API: POST /services/event/startTyping
The body contains 2 values:

accountId: The numeric identifier of the account
accountIdentification: The alphanumeric identifier of the account

If you are using the Web library

This will only trigger if the parleySettings.runOptions.isTypingEnabled setting is enabled.

{
  "type": "event",
  "body": {
    "name": "startTyping",
    "body": {
      "accountId": 1,
      "accountIdentification": "xxxxxxx"
    },
    "user": {
      "id": "11111",
      "uniqueIdentifier": null,
      "additionalInformation": null
    }
  }
}

Stop typing

This is triggered when the user stops typing the current message in the Parley chat window.
API: POST /services/event/stopTyping
The body contains 2 values:

accountId: The numeric identifier of the account
accountIdentification: The alphanumeric identifier of the account

If you are using the Web library

This will only trigger if the parleySettings.runOptions.isTypingEnabled setting is enabled.

{
  "type": "event",
  "body": {
    "name": "stopTyping",
    "body": {
      "accountId": 1,
      "accountIdentification": "xxxxxxx"
    },
    "user": {
      "id": "11111",
      "uniqueIdentifier": null,
      "additionalInformation": null
    }
  }
}

Chat opened

This is triggered when the user opens the Parley chat window.
API: POST /services/event/ChatOpened
The body contains 2 values:

accountId: The numeric identifier of the account
accountIdentification: The alphanumeric identifier of the account

If you are using the Web library

This will only trigger if the parleySettings.runOptions.chatOpenedEnabled setting is enabled.

{
  "type": "event",
  "body": {
    "name": "chatOpened",
    "body": {
      "accountId": 1,
      "accountIdentification": "xxxxxxx"
    },
    "user": {
      "id": "11111",
      "uniqueIdentifier": null,
      "additionalInformation": {
        "key": "value"
      }
    }
  }
}

Action

These are actions that have been triggered from within the Parley admin dashboard. The action section contain more tables since actions can contain a different payload structure.

Property name	Data type	Description
type	`String`	Determines what kind of information the payload provides.
action	`String`	Determines what kind of action took place in the Parley dashboard setting.
body	`Object`	Contains data of the action.
accountIdentification	`String`	The alphanumeric identifier of the Parley account the message was sent to.
user	`Object`	Contains the same information as the `Message` payload. Please view the Message payload.

Change default service

This is trigged when the admin is changing the default service of an attached Service from the Parley account inside the Parley admin dashboard.

oldDefaultService: Contains information about the Service that was selected before the change took place.
newDefaultService: Contains information about the Service that is selected after the change took place.
initiatedBy: Shows which user account has made a change in the dashoard settings.

warning

The admin must have access to edit the Service settings in the Parley admin dashboard.

{
  "body": {
    "action": "changeDefaultService",
    "metadata": "",
    "initiatedBy": "john.doe@parley.nu",
    "oldDefaultService": {
      "name": "Service A",
      "identification": "xxxxxxxx"
    },
    "newDefaultService": {
      "name": "Service B",
      "identification": "yyyyyyyy"
    }
  },
  "accountIdentification": "xxxxxxxx",
  "type": "service"
}

Change owner

This is triggered when the Service changes the owner of the user.
API: PUT/users/{userId}/owner
The body contains 4 values which are type of String and 2 which are Objects:

oldOwner: Contains information about the owner the user was first attached to.
newOwner: Contains updated information about about the owner the user is now attached to.
oldOwner.identification | newOwner.identification: The identification of the the Service (owner)
oldOwner.default | newOwner.default: Whether the Service is the default service or not.

warning

The owner refers to the Service of the current parley account. This action is only triggered if the users' owner is different then the previous owner.

{
  "body": {
    "action": "changeOwner",
    "metadata": "",
    "oldOwner": {
      "name": "Service A",
      "identification": "xxxxxxxx",
      "default": true
    },
    "newOwner": {
      "name": "Service B",
      "identification": "yyyyyyyy",
      "default": false
    },
    "initiatedBy": {
      "name": "Service A",
      "identification": "xxxxxxxx",
      "default": true
    }
  },
  "accountIdentification": "xxxxxxxx",
  "user": {
    "id": 1,
    "uniqueIdentifier": null,
    "additionalInformation": null
  },
  "type": "owner"
}

Message

Just like Events you get Messages in a similar structure. Because all messages use the same structure we will describe all fields below.

Name	Type	Description
type	`String`	Determines what kind of information the payload provides. In this case it will always be `message`.
id	`Integer`	The numeric identifier of the message.
time	`Integer`	The time when the message was send.
message	`String`	The text of the message.
typeId	`Integer`	The type of the message For more info, see the POST /message api call.
accountIdentification	`String`	The alphanumeric identifier of the Parley account the message was sent to.
accountId	`Integer`	The numeric identifier of the Parley account the message was sent to.
requestUrl	`String`	The url from which the message was sent. If the requestUrl could not be found, the field is not shown.
user	`Object`	Contains the user information.
user.id	`String`	Contains the numeric identifier of the current user.
user.uniqueIdentifier	`String`\|`null`	Represents the extern Id which was given to the user when the user logged in, this could be for example a customer id. For more info, see User Registration
user.additionalInformation	`Object`\|`null`	Contains custom information for the current user. For more info, see the POST /devices api call or es: - one for Events https://developers.parley.nu/docs/settings#general for the web library setting.

Text message

This is triggered when the user sends a text message through the Parley chat window.
API: POST /messages.

{
  "id": 180637,
  "time": 1664889410,
  "message": "Test",
  "typeId": 1,
  "accountIdentification": "xxxxxxx",
  "accountId": 1,
  "requestUrl": "https://parleycdn.com",
  "user": {
    "id": "11111",
    "uniqueIdentifier": "customer_1563",
    "additionalInformation": {
      "key": "value"
    }
  },
  "type": "message"
}

Image

This is triggered when the user sends an image through the Parley chat window.
API: POST /messages

{
  "id": 180679,
  "time": 1664895073,
  "message": "{{img/5/2022/10/4/xxxxxxx.png}}",
  "typeId": 1,
  "accountIdentification": "xxxxxxx",
  "accountId": 1,
  "requestUrl": "https://parleycdn.com/",
  "user": {
    "id": "11111",
    "uniqueIdentifier": "customer_1563",
    "additionalInformation": {
      "key": "value"
    }
  },
  "type": "message"
}

Client is registered

This is triggered when the user is registered. It sends a system message (typeId: 4 to the Service(s))
(see User registration for more info).

{
  "id": 22222,
  "time": 1664905828,
  "message": "user_registered",
  "typeId": 4,
  "accountIdentification": "xxxxxxx",
  "accountId": 1,
  "requestUrl": "https://parleycdn.com/",
  "user": {
    "id": "11111",
    "uniqueIdentifier": "customer_1563",
    "additionalInformation": {
      "key": "value"
    }
  },
  "type": "message"
}

If you are using the Web library

The messages: logged_in and deleted_conversation are sent by the Web library. If you have your own front-end, these messages might not be sent.

This is triggered when the client continues the conversation with an authHeader.

{
  "id": 136,
  "time": 1665061013,
  "message": "logged_in",
  "typeId": 4,
  "accountIdentification": "xxxxxxx",
  "accountId": 1,
  "requestUrl": "https://parleycdn.com/",
  "user": {
    "id": "11111",
    "uniqueIdentifier": "customer_1563",
    "additionalInformation": null
  },
  "type": "message"
}

Client deletes the local conversation

This is triggered when the client closes the Parley chat window and deletes their cookies through the Close alert. It sends a system message (typeId: 4 to the Service(s)).

{
  "id": 180658,
  "time": 1664893713,
  "message": "deleted_conversation",
  "typeId": 4,
  "accountIdentification": "xxxxxxx",
  "accountId": 1,
  "requestUrl": "https://parleycdn.com/",
  "user": {
    "id": "11111",
    "uniqueIdentifier": null,
    "additionalInformation": null
  },
  "type": "message"
}

Client merging

This is triggered when the Client logs in after having an anonymous conversation. The "anonymous" user will be merged with it's "registered" counterpart, which means that the identifiers will change.
(see Client API authorization for more info).

Name	Type	Description
updateUser	`Object`	Contains the information about the updated user.
updateUser.oldUserId	`Integer`	The old numeric identifier for the registered user.
updateUser.newUserId	`Integer`	The new numeric identifier for the registered user.
updateUser.uniqueIdentifier	`String`\| `null`	Represents the extern Id which was given to the user when the user logged in, this could be for example a customer id. For more info, see User Registration
updateUser.additionalInformation	`String` \| `null`	Contains custom information for the current user. For more info, see the POST /devices api call or es: - one for Events https://developers.parley.nu/docs/settings#general for the web library setting.
accountId	`Integer`	The numeric identifier of the Parley account the message was sent to.
requestUrl	`String`	The url from which the device was registered. If the requestUrl could not be found, the field is not shown.

{
  "updateUser": {
    "oldUserId": 11111,
    "newUserId": 11112,
    "uniqueIdentifier": "customer_1563",
    "additionalInformation": "{\"key\":\"value\"}"
  },
  "accountId": 1,
  "requestUrl": "https://parleycdn.com/"
}

Event​

Start typing​

Stop typing​

Chat opened​

Action​

Change default service​

Change owner​

Message​

Text message​

Image​

Client is registered​

Client login and continues the conversation​

Client deletes the local conversation​

Client merging​

Event

Start typing

Stop typing

Chat opened

Action

Change default service

Change owner

Message

Text message

Image

Client is registered

Client login and continues the conversation

Client deletes the local conversation

Client merging