> For the complete documentation index, see [llms.txt](https://docs.amitysolutions.com/ekoai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amitysolutions.com/ekoai/api-reference/botv2/botv2-schema/action.md).

# Action

Action Schema

There are actions for the bot to take when a user interact with a controller associated with the action 

## Common Properties

These are common properties for all type of actions

| Field | Required | Type   | Description                                | Restriction                                                                                                                                                                      |
| ----- | -------- | ------ | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| label | false\*  | String | Label for the action                       | <p></p><ul><li>is required for Message of type <code>Button Template</code> and <code>Carousel Template</code> and quick reply object.</li><li>Maximum character is 20</li></ul> |
| area  | false\*  | Object | area of the action (see Area Object below) | is required for Message of type `imagemap`                                                                                                                                       |

### Area Object

| Field  | Required | Type    | Description                                               | Restriction                  |
| ------ | -------- | ------- | --------------------------------------------------------- | ---------------------------- |
| x      | true     | Integer | Horizontal position relative to the left edge of the area | Value must be `0` or higher. |
| y      | true     | Integer | Vertical position relative to the top of the area         | Value must be `0` or higher. |
| width  | true     | Integer | Width of the tappable area                                |                              |
| height | true     | Integer | Height of the tappable area                               |                              |

## Action Types

There are 5 types of actions.

### Message Action

When a message action is prompted, a string in field `text` will be sent as a message from the user

| Field | Required | Type   | Description                            | Restriction |
| ----- | -------- | ------ | -------------------------------------- | ----------- |
| type  | true     | String | Required as `message`                  |             |
| text  | true     | String | Text sent when the action is performed |             |

#### Example

{% tabs %}
{% tab title="Message Action ex1" %}

```
//In Message of type Button Template and Carousel Template and quick reply object
{
    "type":"message",
    "text":"This is a user's message",
    "label":"users message" 
}
```

{% endtab %}

{% tab title="Message Action ex2" %}

```
/In Message of type imagemap
{
    "type":"message",
    "text":"This is a user's message",
    "area": {
        "x":0,
        "y":0,
        "width":20,
        "height":20
    }
}
```

{% endtab %}
{% endtabs %}

### Postback Action

When a postback action is prompted, a postback `event` is returned via webhook

| Field | Required | Type   | Description                                                                           | Restriction |
| ----- | -------- | ------ | ------------------------------------------------------------------------------------- | ----------- |
| type  | true     | String | Required as `postback`                                                                |             |
| data  | true     | String | String returned via webhook                                                           |             |
| text  | false    | String | Text displayed in the chat as a message sent by the user when the action is performed |             |

#### Example

{% tabs %}
{% tab title="Postback Action ex1" %}

```
//In Message of type Button Template and Carousel Template and quick reply object
{
   "type":"postback",
   "data":"action=buy&itemid=111",
   "text":"Buy",
   "label":"Buy"
}
```

{% endtab %}

{% tab title="Postback Action ex2" %}

```
/In Message of type imagemap
{
    "type":"postback",
    "data":"action=buy&itemid=111",
    "text":"Buy",
    "area": {
        "x":0,
        "y":0,
        "width":20,
        "height":20
    }
}
```

{% endtab %}
{% endtabs %}

### Workflow Template Action

When a control associated with this action is tapped, a workflow template will be prompted to the user

| Field      | Required | Type    | Description                    | Restriction |
| ---------- | -------- | ------- | ------------------------------ | ----------- |
| type       | true     | String  | Required as `workflowTemplate` |             |
| templateId | true     | Stringe | workflow template ID           |             |

#### Example

{% tabs %}
{% tab title="Workflow Template Action ex1" %}

```
//In Message of type Button Template and Carousel Template and quick reply object
{
   "type":"workflowTemplate",
   "templateId":"5d7385a4edde5726453d49dc",
   "label":"Leave workflow template"
}
```

{% endtab %}

{% tab title="Workflow Template Action ex2" %}

```
/In Message of type imagemap
{
    "type":"workflowTemplate",
    "templateId":"5d7385a4edde5726453d49dc",
    "area": {
        "x":0,
        "y":0,
        "width":20,
        "height":20
    }
}
```

{% endtab %}
{% endtabs %}

### Workflow Action

When a control associated with this action is tapped, the workflow will be prompted to the user

| Field      | Required | Type   | Description            | Restriction |
| ---------- | -------- | ------ | ---------------------- | ----------- |
| type       | true     | String | Required as `workflow` |             |
| workflowId | true     | String | The user's workflow ID |             |

#### Example

{% tabs %}
{% tab title="Workflow Action ex1" %}

```
// In Message of type Button Template and Carousel Template and quick reply object
{
   "type":"workflow",
   "workflowId":"5d73870fedde5726453d49e0",
   "label":"Your pending workflow"
}
```

{% endtab %}

{% tab title="Workflow Action ex2" %}

```
// In Message of type imagemap
{
    "type":"workflow",
    "workflowId":"5d73870fedde5726453d49e0",
    "area": {
        "x":0,
        "y":0,
        "width":20,
        "height":20
    }
}
```

{% endtab %}
{% endtabs %}

### Workflows Action

When a control associated with this action is tapped, the user will be redirect to the Workflows page.

| Field  | Required | Type   | Description                                       | Restriction                                                   |
| ------ | -------- | ------ | ------------------------------------------------- | ------------------------------------------------------------- |
| type   | true     | String | Required as `workflows`                           |                                                               |
| status | false    | String | The workflow status, used to filter the Workflows | 'awaiting', 'processing', 'completed', 'rejected', 'canceled' |

{% tabs %}
{% tab title="Workflows Action ex1" %}

```
// In Message of type Button Template and Carousel Template and quick reply object
{
   "type":"workflows",
   "status":"awaiting",
   "label":"Your awaiting workflows"
}
```

{% endtab %}

{% tab title="Workflows Action ex2" %}

```
// In Message of type imagemap
{
    "type":"workflows",
    "status":"processing",
    "area": {
        "x":0,
        "y":0,
        "width":20,
        "height":20
    }
}
```

{% endtab %}
{% endtabs %}

### Library Action

When a control associated with this action is tapped, the user will be redirect to the corresponding Library document.

#### Example

{% tabs %}
{% tab title="Example 1" %}

```
// In Message of type Button Template and Carousel Template and quick reply object
{
   "type": "library",
   "label": "2020 Public Holidays",
   "url": "https://h1.eko12.local?redirect_path=doc%2F5e620b89cd88e30014a13e9c&eko_action=open_library"
}
```

{% endtab %}

{% tab title="Example 2" %}

```
// In Message of type imagemap
{
   "type": "library",
   "label": "2020 Public Holidays",
   "url": "https://h1.eko12.local?redirect_path=doc%2F5e620b89cd88e30014a13e9c&eko_action=open_library"
   "area": {
      "x":0,
      "y":0,
      "width":20,
      "height":20
    }
}
```

{% endtab %}
{% endtabs %}

### URI Action

When a control associated with this action is tapped, the URI specified in the `linkUri` property is opened.

| Field   | Required | Type    | Description                             | Restriction |
| ------- | -------- | ------- | --------------------------------------- | ----------- |
| type    | true     | String  | Required as `uri`                       |             |
| linkUri | true     | Stringe | URI opened when the action is performed |             |

#### Example

{% tabs %}
{% tab title="URI Action ex1" %}

```
//In Message of type Button Template and Carousel Template and quick reply object
{
   "type":"uri",
   "linkUri":"https://ekogreen.ekoapp.com",
   "label":"Buy"
}
```

{% endtab %}

{% tab title="URI Action ex2" %}

```
/In Message of type imagemap
{
    "type":"uri",
    "linkUri":"https://ekogreen.ekoapp.com",
    "area": {
        "x":0,
        "y":0,
        "width":20,
        "height":20
    }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amitysolutions.com/ekoai/api-reference/botv2/botv2-schema/action.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.