Add Message

Sends a message the visitor sees, live, in the Beacon widget.

Only the agent a chat is assigned to may message the customer. An unassigned chat is accepted automatically; a chat held by someone else returns 400.

Request

PUT /v2/chats/5a0da3c3-4882-3352-8db9-8fc47e14111f/messages/6ef1eeee-8419-46b5-a80d-f36a713898d4 HTTP/1.1
Authorization: Bearer oauth_token
Content-Type: application/json

{
  "body": "Rayleigh scattering — shorter blue wavelengths scatter more."
}

Path Parameters

/v2/chats/{chatId}/messages/{messageId}

Request Body

The message id is yours to choose

{messageId} is a UUID the caller generates. Sending the same one twice returns 422 id value is already in use rather than posting the message again, so retrying after a timeout is safe if you treat that error as success.

The visitor sees the name of the user your app acts as

An app authenticates as itself and Help Scout resolves it to the user who created it. The widget shows that user’s first name and last initial, so a user called Jack Sprout appears as Jack S.

If the sender is software, say so. Name the user so a visitor can tell, and introduce it once at the start of a chat. Several markets require that disclosure outright.

Response

Every write answers with the chat, in the same shape Get Chat returns — so a caller sees the result of what it just did without a follow-up read.

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "id": "5a0da3c3-4882-3352-8db9-8fc47e14111f",
  "beaconId": "ed8e9fe0-acf4-4b44-b1fc-a5bff956e7a8",
  "mailboxId": 2599,
  "createdAt": "2020-07-03T07:03:29.982028Z",
  "assignee": { "id": 4440, "type": "agent", "first": "Jack", "last": "Sprout" },
  "customer": { "id": 498746, "type": "customer", "first": "Vernon", "last": "Bear" },
  "_embedded": {
    "events": [ "..." ]
  },
  "_links": {
    "self": { "href": "..." }
  }
}

The full field reference is on Get Chat.

Errors