Messages

How to list, get and create ticket messages

Request Overview

Requests

Get All Ticket Messages

GET /api/v1/tickets/{id}/messages Returns, a collection of ticket messages

GET /api/v1/tickets/{{id}}/messages HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

200 Response

HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "data": [
    {
       "id": 5465,
       "body": "<p>Some Message</p>",
       ...
    },
    {
       "id": 5466,
       "body": "<p>Some Message</p>",
       ...
    },
    ...
  ],
  "links": {
    ...
  },
  "meta": {
    ...
  }
}

Information about links and meta please read this article.

Query parameters

By default, the massage API will return only the default message types, but it's possible to request additional-types or just specific types.

For example: /api/v1/tickets/{id}/messages?additional-types[]=internal

Get One Ticket Message

GET /api/v1/tickets/{ticket_id}/messages/{message_id} Returns the message object

GET /api/v1/tickets/{{ticket_id}}/messages/{{message_id}} HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

200 Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: gzip
...

{
  "data": {
    "id": 17916,
    "from_contact": {},
    "type": "external",
    ...
    "body": "<p>Some body text.<\/p>",
    "inline_images": [],
    "attachments": [],
    "created_at": "2022-04-21T10:24:40+00:00"
  },
}

Get Media Stream - Inline Image

GET /api/v1/media/inline/{id}/{?size} Returns a media stream

If you want to download the image in a smaller size, you can choose between medium and large.

GET /api/v1/media/inline/{{id}}/{{?size}} HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

Get Media Stream - Attachment

GET /api/v1/media/attachment/{id} Returns a media stream

GET /api/v1/media/attachment/{{id}} HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

Create new Ticket Message

POST /api/v1/tickets/{id}/messages Creates a new message on a ticket.

POST /api/v1/tickets/{{id}}/messages HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

{   
    "id": "34343",
    "from_contact": {
        "name": "My Custom Name",
        "email": "some.name@customer.de",
        ...
    },
    "body": "<p>Hi, see my inline image <img src=\"cid:fovdffoo1@bar.net\"> <\/p>",
    "cc": ["cc@test.de"],
    "bcc": ["bcc@test.de"],
    "fwd": ["fwd@test.de"],
    "inline_images": [
        {
            "cid": "fovdffoo1@bar.net",
            "name": "inline-image.png",
            "mime_type": "image/png",
            "data" : "iVBORw0KGgoAAAANSUhEUg"
        }
    ],
    "attachments": [
        {
            "name": "attachments-image.png",
            "mime_type": "image/png",
            "data" : "iVBORw0KGgoAAAANS"
        }
    ]
}

201 Response

HTTP/1.1 201 OK
Content-Type: application/json
...

{
  "data": {
    "id": 17916,
    "from_contact": {
      "id": 1013,
      "user_id": 1018,
      "name": "My Custom Name",
      "value": "someones2554@example.com",
      "type": "email"
    },
    "type": "external",
    "cc": ["cc@test.de"],
    "bcc": ["bcc@test.de"],
    "fwd": ["fwd@test.de"],
    "body": "<p>Hi, see my inline image <img src=\"cid:12321\" class=\"spm-message-inline-image\" alt=\"12322\"> <\/p>",
    "inline_images": [
      {
        "id": 12321,
        "url": "http:\/\/api.help\/api\/v1\/media\/inline\/12321",
        "file_type": "image",
        "file_name": "inline-image.png",
        "mime_type": "image\/png",
        "size": 144,
        "created_at": "2022-04-21T10:24:40+00:00"
      }
    ],
    "attachments": [
      {
        "id": 12323,
        "url": "http:\/\/api.help\/api\/v1\/media\/inline\/12323",
        "file_type": "image",
        "file_name": "attachment-image.png",
        "mime_type": "image\/png",
        "size": 144,
        "created_at": "2022-04-21T10:24:42+00:00"
      }
    ],
    "created_at": "2022-04-21T10:24:40+00:00"
  },
}

Note: Creating messages with inline images
If you want to create messages with inline images, you need to set up a content-id (cid) in the body IMG tag that corresponds to a content-id of your delivered inline_images. If an inline image could not be found in the body, it will be added as an attachment.

 "body": "<p>Hi, see my inline image <img src=\"cid:fovdffoo1@bar.net\"> <\/p>",
 "inline_images": [
     {
         "cid": "fovdffoo1@bar.net",
         ...
     }
 ],

Request Objects

Message field list

Inline image object

 <img src=\"cid:fovdffoo1@bar.net\">

Request attachment object

Response Objects

Message field list

Attachment and Inline Image field list