What's my plan?
Add-on AI agents - Advanced

A template is a specific version of a reply for advanced AI agents that you can use over and over in conversation flows, or dialogues.

You can’t create templates with the AI Agents Advanced add-on dashboard if your bot is integrated through messaging rather than directly with Sunshine Conversations. If you attempt to do so, you will receive the following error: bot is not authorized. However, if your bot uses messaging integration, this article shows how to create templates by making requests to the Sunshine Conversations v1 API and how to apply the shorthand within a dialogue flow.

Note: If your bot is integrated directly with Sunshine Conversations, see Creating templates for advanced AI agents with Sunshine Conversations.

This article includes these sections:

  • Creating the Conversation API keys
  • Downloading the Sunshine Conversations Postman collection
  • Authorizing Postman
  • Creating the template
  • Applying the shorthand in a dialogue flow

Creating the Conversation API keys

Sunshine Conversations API requests require authentication through either Basic authentication or JSON Web Tokens (JWTs). Both methods require an API key.

You can create these keys using the Conversations API page. For more information, see Using the Conversations API keys. Copy and store the App ID, Key ID, and secret key in a secure location as you'll need them later.

Downloading the Sunshine Conversations Postman collection

Zendesk recommends using Postman to make requests to the Sunshine Conversations v1 API.

A prebuilt Sunshine Conversations Postman collection is available, including example requests for creating and managing templates.

To download the Sunshine Conversations v1 Postman collection

  • If you already have Postman installed or want to use Postman for Web, click Run in Postman.
  • To download the collection without directly importing it into Postman, click Download collection and save the file to your local drive using your browser's specific download method. The collection is in JSON format and can be manually imported into Postman.

Your new collection is named Smooch within Postman.

Authorizing Postman

Before sending authenticated requests to the Sunshine Conversations API with Postman, you need to configure Postman using your API credentials. This authorization step verifies your identity and grants secure access to your data for authorized operations.
Note: The following steps assume you imported the Sunshine Converations collection into Postman.

To authorize Postman with your Conversations API keys

  1. In Postman, click the Smooch collection.
  2. Click the Variables tab.
  3. Add variables keyId, appId, and secret and enter their corresponding values from your Conversation Keys into the Current value column.
  4. Add variables url and apiVersion, and enter https://{subdomain}.zendesk.com/sc and v1.1 as their current values, respectively. Replace {subdomain} with your subdomain name.

  5. Click Save in the upper right corner.
  6. Click the Authorization tab.
  7. Click the Auth type menu and select Basic Auth.
  8. Enter {{keyId}} in the Username field and {{secret}} in the Password field to reference the values from the Variables tab.

  9. Click Save.

Creating the template

The Sunshine Conversations v1 API is the core service that creates and manages templates on the server. To create a template, you send a request directly to the Create Templates endpoint.

The imported Sunshine Conversations collection includes example requests to create templates, which you can customize with your template details. When you finalize your template details in Postman and click Send, Postman sends the HTTP request directly to the Sunshine Conversations API. The API then processes the request and creates or updates the template on the server.

See Template messages for sample templates and instructions for creating your own template using the Create Templates endpoint.

To create your template
  1. In Postman, open the Smooch collection, then select Templates > Create Template Examples.
  2. Select an example template and fill in the request body with your details, or create a new one.

    Specify a name in the request body instead of using the default value. You'll use this name in the next section.

    {
    "name": "my-test-template",
    "message": {
    	   "type": "text",
        "role": "appMaker",
        "text": "This is a text template"
    }
}
  3. Click Send to submit the request and create the template. You'll receive a JSON response similar to the following. 
    {
    "template": {
        "_id": "688113ef4a286305984b70c0",
        "message": {
            "role": "appMaker",
            "type": "text",
            "text": "This is a text template"
        },
        "name": "my-test-template",
        "isLarge": false
    }
}

Applying the shorthand in a dialogue flow

To send a template in a conversation, use the dedicated shorthand syntax within an AI Agent message block. A shorthand is a simple syntax you insert within a dialog message block to reference and send a pre-created template message. Instead of rewriting the full message content each time, you use the shorthand to tell the AI agent to fetch and deliver the stored template by its name.

To ensure the AI agent sends the template, the shorthand must be added to an AI Agent message block within the dialogue builder.

To apply the shorthand
  1. In AI Agents - Advanced, click Content > Use cases.
  2. Select the use case for the dialogue you want to send the template.
  3. Click Edit dialogue.
  4. Add an AI Agent message block to the flow.

    The template you specify will be sent at the exact point within the dialogue flow where you place this block.

  5. Within the new block, insert the template using the shorthand syntax %((template:value_of_name_field))%.

    Replace value_of_name_field with the name you defined in Creating the template.

  6. Click Save.
  7. Click Publish.

To test your template, use a live widget embedded in either your Help Center or website. For example, you can create a basic HTML page and embed the widget from the messaging tab in Admin Center. Alternatively, you can also test using your live or production bot. The test dialogue in AI Agents - Advanced does not connect to external customer data systems, so actions involving those systems cannot be executed during testing. Instead, the test bot is primarily designed to verify the accuracy of dialogue flows.

Powered by Zendesk