# 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

**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" 
}
```

**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
    }
}
```

### 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

**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"
}
```

**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
    }
}
```

### 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

**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"
}
```

**Workflow Template Action ex2**

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

### 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

**Workflow Action ex1**

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

**Workflow Action ex2**

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

### 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' |

**Workflows Action ex1**

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

**Workflows Action ex2**

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

### Library Action

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

#### Example

**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"
}
```

**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
    }
}
```

### 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

**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"
}
```

**URI Action ex2**

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