Shorthand syntax
Shorthand syntax can be used to add rich messaging support in places where it might not otherwise be possible. For example, if you use a third-party bot with Zendesk messaging, but your bot vendor does not have support for configuring rich messages such as carousel messages or action buttons, shorthand syntax can be used to circumvent this limitation.
Quick reference
| Element | Syntax | Example |
|---|---|---|
| Link button | %[]() | %[Button label](https://anyurl.com) |
| Reply button | %[](reply:) | %[Button label](reply:PAYLOAD) |
| Postback button | %[](postback:) | %[Button label](postback:PAYLOAD) |
| Image | ![]() |  |
| Template message | %((template:))% or %{{template:}}% | %((template:TEMPLATE_NAME))% |
| WhatsApp Message Template | &((namespace=[[]] template=[[]] fallback=[[]] language=[[]] body_text=[[]]))& | &((namespace=[[namespace]] template=[[template]] fallback=[[text_fallback]] language=[[language]] body_text=[[param_1]]))& |
Sending syntax
To send a rich message using shorthand syntax, add the syntax within a text type message in either the text, htmlText or markdownText properties. As part of validating the message, the syntax will be parsed out of the text field, and the message will be transformed according to the syntax used.
For example, the following call to the Post Message API includes shorthand syntax for two link buttons:
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id}/messages \-X POST \--user '{key_id}:{secret}' \-H 'content-type: application/json' \-d '{"author": {"type": "business"},"content": {"type": "text","text": "Follow one of the links below %[Link 1](https://example.com) %[Link 2](https://example2.com)"}}'
The following message will be produced as a result:
{"id": "687151a3667d93d30b977775","received": "2025-01-01T00:00:00.000Z","author": {"avatarUrl": "https://www.gravatar.com/avatar/00000000000000000000000000000000.png?s=200&d=mm","type": "business"},"content": {"type": "text","text": "Follow one of the links below","actions": [{"type": "link","text": "Link 1","uri": "https://example.com"},{"type": "link","text": "Link 2","uri": "https://example2.com"}]},"source": {"type": "api:conversations"}}
Compound messages
It's possible to combine action button syntax and image syntax together to produce a compound message including any combination of text, image, and action buttons.
Here is an example of a compound message including all three components:
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id}/messages \-X POST \--user '{key_id}:{secret}' \-H 'content-type: application/json' \-d '{"author": {"type": "business"},"content": {"type": "text","text": "Pre-wrapped cat  %[Purchase cat](https://i.ytimg.com/vi/tntOCGkgt98/maxresdefault.jpg)"}}'
which will result in the following message:
{"messages": [{"id": "6871549376808bbb33bf1a28","received": "2025-01-01T00:00:00.000Z","author": {"avatarUrl": "https://www.gravatar.com/avatar/00000000000000000000000000000000.png?s=200&d=mm","type": "business"},"content": {"type": "image","text": "Pre-wrapped cat","actions": [{"type": "link","text": "Purchase cat","uri": "https://i.ytimg.com/vi/tntOCGkgt98/maxresdefault.jpg"}],"mediaUrl": "https://i.ytimg.com/vi/tntOCGkgt98/maxresdefault.jpg","mediaType": "image/jpeg","mediaSize": 1097,"altText": "maxresdefault.jpg"},"source": {"type": "api:conversations"}}]}
Template messages
See sending a template message for details on how the template syntax is used to produce a message from a template.
WhatsApp Message Templates
The shorthand syntax for WhatsApp Message Templates includes several parameters necessary for building the content of your template message. For details on how to send message templates using JSON, see message overrides instead.
The WhatsApp Message Template syntax includes a sequence of key-value pairs as shown in the following sample:
&((namespace=[[namespace]]template=[[template]]fallback=[[fallback]]language=[[language]]header_image/header_document/header_text=[[https://image.jpg/...]]header_filename=[[My File]]body_text=[[param_1]]body_text=[[param_2]]button_index=[[0]]button_payload=[[payload]]button_index=[[1]]button_url=[[channels/whatsapp]]))&
namespace: The namespace within which the Message Template is defined (WhatsApp portal)
template: The name or "element_name" of your Message Template (WhatsApp portal)
language: The language of your Message Template (WhatsApp portal)
body_text: A variable in the list of parameters that will be inserted into the relevant fields in the Message Template. This can be provided as many times as the amount of variables in the template. For a template without variables, this should not be used.
header_image/header_document/header_text: The variable text or media url that will be used for the header of the message. You can't use more than one header. For header_image or header_document, the url to the media must be provided.
header_filename: The variable file name that will be used to title the header_document file sent to WhatsApp. This can only appear directly after header_document.
button_index: The variable button index that will be used in the button component of the message. This must be supplied before button_url or button_payload, and it must match the index of the button in the actual WhatsApp template.
button_payload: The variable payload used for quick reply actions sent to WhatsApp. This must be supplied after button_index. The payload will be reflected in the resulting webhook.
button_url: The variable used for dynamic URL actions sent to WhatsApp. This must be supplied after button_index. The value will be appended to the dynamic URL set in the WhatsApp Message Template.
fallback: Only used if message template reconstruction fails. Typically, the message.text field in the conversation record will be populated automatically by reconstructing the template. If this process fails, the fallback supplied here will be used instead