Response Format Examples for Custom Connections

Use these examples as starting points when you design AiResponseFormat entries for your own custom connection. To reference an AiResponseFormat from your AiSurface see, Set Up a Custom Connection.

For background on how the agent selects a response format and why client-side validation matters, see Custom Connections.

Text Choices

Use this format when you want to present the user with a short list of text-only options, such as a menu or a disambiguation prompt.

1<?xml version="1.0" encoding="UTF-8"?>
2<AiResponseFormat xmlns="http://soap.sforce.com/2006/04/metadata">
3    <description>A response action for AcmeChatClient. Use this to prompt the user to select one of many available text choices when the number of choices is GREATER THAN 1 and LESSER THAN 8.</description>
4    <input>{"type":"object","properties":{"message":{"type":"string","description":"Placeholder for message input"},"choices":{"type":"array","items":{"type":"string"}}},"required":["message","choices"]}</input>
5    <instructions>
6        <instruction>Always use AcmeChatChoices when showing choice text responses with GREATER THAN 1 choice and LESS THAN 8 choices to the user.</instruction>
7        <sortOrder>1</sortOrder>
8    </instructions>
9    <masterLabel>Acme Chat Choice Response</masterLabel>
10</AiResponseFormat>

Choices with Images

Use this format when the user is selecting from a collection of items where an image is essential to the decision—product listings, location cards, or avatar pickers.

1<?xml version="1.0" encoding="UTF-8"?>
2<AiResponseFormat xmlns="http://soap.sforce.com/2006/04/metadata">
3    <description>A response action for AcmeChatClient. Use this to prompt the user to select one of many choices with accompanying images, such as product listings.</description>
4    <input>{"type":"object","properties":{"message":{"type":"string","description":"Placeholder for message input"},"choices":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"imageUrl":{"type":"string"},"actionText":{"type":"string"}},"required":["title","imageUrl","actionText"]}}},"required":["message","choices"]}</input>
5    <instructions>
6        <instruction>Always use AcmeChatChoicesWithImages when showing choices with images with GREATER THAN 1 choice and LESS THAN 8 choices to the user.</instruction>
7        <sortOrder>2</sortOrder>
8    </instructions>
9    <masterLabel>Acme Chat Choice With Images</masterLabel>
10</AiResponseFormat>

Time Picker

Use this format when you need the user to pick a specific time. The schema below follows Slack Block Kit timepicker syntax, which is a useful reference if your client already renders Block Kit components.

1<?xml version="1.0" encoding="UTF-8"?>
2<AiResponseFormat xmlns="http://soap.sforce.com/2006/04/metadata">
3    <description>A response action for AcmeChatClient. Use this to prompt the user to select a time using a time picker component.</description>
4    <input>
5{
6  "type": "object",
7  "properties": {
8    "type": { "const": "section" },
9    "text": {
10      "type": "object",
11      "properties": {
12        "type": { "const": "mrkdwn" },
13        "text": { "type": "string" }
14      },
15      "required": ["type", "text"],
16      "additionalProperties": false
17    },
18    "accessory": {
19      "type": "object",
20      "properties": {
21        "type": { "const": "timepicker" },
22        "initial_time": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" },
23        "placeholder": {
24          "type": "object",
25          "properties": {
26            "type": { "const": "plain_text" },
27            "text": { "type": "string" },
28            "emoji": { "type": "boolean" }
29          },
30          "required": ["type", "text", "emoji"],
31          "additionalProperties": false
32        },
33        "action_id": { "type": "string" }
34      },
35      "required": ["type", "initial_time", "placeholder", "action_id"],
36      "additionalProperties": false
37    }
38  },
39  "required": ["type", "text", "accessory"],
40  "additionalProperties": false
41}
42    </input>
43    <instructions>
44        <instruction>Use AcmeChatTimePicker when you need the user to select a specific time. The response must conform to Slack Block Kit timepicker syntax.</instruction>
45        <sortOrder>3</sortOrder>
46    </instructions>
47    <masterLabel>Acme Chat Time Picker</masterLabel>
48</AiResponseFormat>

The time picker schema expects the agent to produce output in this format:

1{
2  "type": "section",
3  "text": {
4    "type": "mrkdwn",
5    "text": "Section block with a timepicker"
6  },
7  "accessory": {
8    "type": "timepicker",
9    "initial_time": "13:37",
10    "placeholder": {
11      "type": "plain_text",
12      "text": "Choose a time",
13      "emoji": true
14    },
15    "action_id": "meeting_time_picker"
16  }
17}

Tips for Designing Your Own Response Formats

Keep the set small. We recommend fewer than 7 response formats per connection. Too many formats make it harder for the agent to reliably pick the right one.
Write the description for selection, not for humans. The agent uses the description and instructions to decide whether a format applies. Spell out the exact conditions—number of items, presence of images, data shape—in natural language.
Generate the JSON schema with an LLM. Provide your preferred LLM with the output structure your client expects and ask it to generate the corresponding JSON schema.

Response Format Examples for Custom Connections

Text Choices

Choices with Images

Time Picker

Tips for Designing Your Own Response Formats

See Also