Articles

General information about ticket articles

Some attributes of articles might not be straight forward or come with fairly many options - below list hopefully helps you on this journey.

content_type

Zammad supports text/html for HTML formatted text or text/plain for plain text. This allows you to have better formatting options if you need them.

Hint

Zammad web UI usually uses text/html.

type

Zammad supports a huge number of article types. Below list may be incomplete depending on your instance and possibly installed add-ons / custom changes.

Note

💬 If not stated otherwise, all article types below are communication articles and thus affecting SLA calculation in Zammad defaults.

😖 What’s the difference?!

Communication articles provide the option to reply automatically. Which actions exactly are available depends on the article type and e.g. recipient lists.

email

This allows you to create incoming or outgoing email articles.

Hint

This allows you to send Email via API. However, this highly depends on the chosen sender.

phone

Indicates phone notes.

web

Usually used by customers only. This type is being used when ever your customer uses the web UI to create articles.

note

When ever a communication does not fit (e.g.: internal notes) choose note. Zammad also uses this article type as default fall back.

Note

😶 This is not a communication article.

sms

This type is being used for Zammads SMS integration.

chat

This article type is technically a place holder and is only available via API.

fax

This article type is technically a place holder and is only available via API.

twitter status & twitter direct-message

These articles types are used by Zammads twitter channel. Technically you can use these to automatically respond to existing requests via twitter.

facebook feed post & facebook feed comment

These articles types are used by Zammads facebook channel. Technically you can use these to automatically respond to existing requests via facebook.

telegram personal-message

Used by Zammads Telegram channel. Technically you can use these to automatically respond to existing requests via Telegram.

internal

This attribute allows you to set the visibility of your articles. For internal visible only use true, for visibly for your customers as well use false.

Warning

🔒 Visibility: internal doesn’t mean it’s silent

If you set an article to internal: true but choose to send an email, please be aware that said Email is still being sent out!

sender

Indicates which use did create the article. You can choose from:

• Agent

• Customer

• System

Warning

Depending of above selection, some article types may not be available or behave different. Please be aware that System causes users not being able to read the bodies (this works similar to Zammads trigger displaying in tickets).

List Articles by Ticket

Required permission: ticket.agent or ticket.customer

GET-Request sent: /api/v1/ticket_articles/by_ticket/{ticket id}

Response:

# HTTP-Code 200 OK

[
   {
      "id": 9,
      "ticket_id": 5,
      "type_id": 1,
      "sender_id": 2,
      "from": "David Bell <david@example.com>",
      "to": "order@chrispresso.com",
      "cc": null,
      "subject": null,
      "reply_to": null,
      "message_id": null,
      "message_id_md5": null,
      "in_reply_to": null,
      "content_type": "text/html",
      "references": null,
      "body": "Hi,<br>\n<br>\n<u>please send me:</u><br>\n1 x Café Kopi susu<br>\n4 x Viennese melange<br>\n<br>\n<u>Delivery Address:</u><br>\nDavid Bell<br>\nEiffel Tower<br>\n5 Avenue Anatole France<br>\n75007 Paris<br>\n<span class=\"js-signatureMarker\"></span>\n<br>\nDavid Bell",
      "internal": false,
      "preferences": {},
      "updated_by_id": 10,
      "created_by_id": 10,
      "origin_by_id": null,
      "created_at": "2021-08-02T11:57:18.068Z",
      "updated_at": "2021-08-02T11:57:18.068Z",
      "attachments": [],
      "type": "email",
      "sender": "Customer",
      "created_by": "david@example.com",
      "updated_by": "david@example.com"
   },
   {
      "id": 10,
      "ticket_id": 5,
      "type_id": 1,
      "sender_id": 1,
      "from": "Emma Taylor via <order@chrispresso.com>",
      "to": "David Bell <david@example.com>",
      "cc": null,
      "subject": null,
      "reply_to": null,
      "message_id": null,
      "message_id_md5": null,
      "in_reply_to": null,
      "content_type": "text/html",
      "references": null,
      "body": "Hi David,<br>\n<br>\nnice, we will ship it to your delivery address:<br>\n<br>\nEiffel Tower\n5 Avenue Anatole France\n75007 Paris.<br>\n<br>\nYou will get it till Wednesday.<br>\n<span class=\"js-signatureMarker\"></span>\n<br>\n--<br>\nGreetings,<br>\n<br>\nEmma Taylor<br>",
      "internal": false,
      "preferences": {},
      "updated_by_id": 5,
      "created_by_id": 5,
      "origin_by_id": null,
      "created_at": "2021-08-03T09:57:18.121Z",
      "updated_at": "2021-08-03T09:57:18.121Z",
      "attachments": [],
      "type": "email",
      "sender": "Agent",
      "created_by": "emma@chrispresso.com",
      "updated_by": "emma@chrispresso.com"
   }
]

List specific article

Required permission: ticket.agent or ticket.customer

GET-Request sent: /api/v1/ticket_articles/{article id}

Response:

# HTTP-Code 200 OK

{
   "id": 9,
   "ticket_id": 5,
   "type_id": 1,
   "sender_id": 2,
   "from": "David Bell <david@example.com>",
   "to": "order@chrispresso.com",
   "cc": null,
   "subject": null,
   "reply_to": null,
   "message_id": null,
   "message_id_md5": null,
   "in_reply_to": null,
   "content_type": "text/html",
   "references": null,
   "body": "Hi,<br>\n<br>\n<u>please send me:</u><br>\n1 x Café Kopi susu<br>\n4 x Viennese melange<br>\n<br>\n<u>Delivery Address:</u><br>\nDavid Bell<br>\nEiffel Tower<br>\n5 Avenue Anatole France<br>\n75007 Paris<br>\n<span class=\"js-signatureMarker\"></span>\n<br>\nDavid Bell",
   "internal": false,
   "preferences": {},
   "updated_by_id": 10,
   "created_by_id": 10,
   "origin_by_id": null,
   "created_at": "2021-08-02T11:57:18.068Z",
   "updated_at": "2021-08-02T11:57:18.068Z",
   "attachments": [],
   "type": "email",
   "sender": "Customer",
   "created_by": "david@example.com",
   "updated_by": "david@example.com"
}

Create

Required permission: ticket.agent or ticket.customer

Tip

If you want to create articles on behalf other users (e.g. for a phone note), use the origin_by_id attribute. ticket.agent permission is mandatory for this.

POST-Request sent: /api/v1/ticket_articles

Plain articleArticle with attached filesArticle with inline images

{
   "ticket_id": 5,
   "subject": "Call note",
   "body": "Called the customer and discussed their issues.<br/>Turns out these were caused by invalid configurations - solved.",
   "content_type": "text/html",
   "type": "phone",
   "internal": false,
   "sender": "Agent",
   "time_unit": "15"
}

Response:

# HTTP-Code 201 Created

{
   "id": 33,
   "ticket_id": 5,
   "type_id": 5,
   "sender_id": 1,
   "from": "Christopher Miller",
   "to": null,
   "cc": null,
   "subject": "Call note",
   "reply_to": null,
   "message_id": null,
   "message_id_md5": null,
   "in_reply_to": null,
   "content_type": "text/html",
   "references": null,
   "body": "Called the customer and discussed their issues.<br>Turns out these were caused by invalid configurations - solved.",
   "internal": false,
   "preferences": {},
   "updated_by_id": 3,
   "created_by_id": 3,
   "origin_by_id": null,
   "created_at": "2021-11-08T16:13:35.962Z",
   "updated_at": "2021-11-08T16:13:35.962Z",
   "attachments": [],
   "type": "phone",
   "sender": "Agent",
   "created_by": "chris@chrispresso.com",
   "updated_by": "chris@chrispresso.com"
}

Receive attachments

Now that you have all those fancy attachments within your tickets, you may want to download specific ones.

GET-Request sent: /api/v1/ticket_attachment/{ticket id}/{article id}/{attachment id}

Response:

Hint

If you’re not sure which articles a ticket / article contains, please retrieve affected articles first.