# Custom Actions

> API endpoints for managing custom action buttons

Source: https://docs.soosh.io/reference/api/custom-actions/

## Overview

Custom Actions are configurable buttons that appear in the chat interface, enabling quick integrations with external systems. Actions can call webhooks, open URLs, or execute JavaScript code.

## List Custom Actions

Retrieve all custom actions for your organization.

`GET /api/custom-actions`

### Response

```json
{
  "status": "success",
  "data": {
    "custom_actions": [
      {
        "id": "uuid",
        "name": "Create Ticket",
        "icon": "ticket",
        "action_type": "webhook",
        "config": {
          "url": "https://api.helpdesk.com/tickets",
          "method": "POST",
          "headers": { "Authorization": "Bearer token" },
          "body": "{\"subject\": \"{{contact.name}}\"}"
        },
        "is_active": true,
        "display_order": 0,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}
```

## Get Custom Action

Retrieve a single custom action by ID.

`GET /api/custom-actions/{id}`

### Response

```json
{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Create Ticket",
    "icon": "ticket",
    "action_type": "webhook",
    "config": {
      "url": "https://api.helpdesk.com/tickets",
      "method": "POST",
      "headers": {},
      "body": ""
    },
    "is_active": true,
    "display_order": 0,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

## Create Custom Action

Create a new custom action.

`POST /api/custom-actions`

### Request Body

```json
{
  "name": "Create Support Ticket",
  "icon": "ticket",
  "action_type": "webhook",
  "config": {
    "url": "https://api.helpdesk.com/tickets",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    "body": "{\"subject\": \"WhatsApp: {{contact.name}}\", \"phone\": \"{{contact.phone_number}}\"}"
  },
  "is_active": true,
  "display_order": 0
}
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Display name for the action button |
| `icon` | string | No | Icon identifier (ticket, user, link, phone, mail, etc.) |
| `action_type` | string | Yes | Type of action: `webhook`, `url`, or `javascript` |
| `config` | object | Yes | Configuration object (varies by action type) |
| `is_active` | boolean | No | Whether the action is enabled (default: true) |
| `display_order` | integer | No | Sort order for display (default: 0) |

### Config by Action Type

#### Webhook Config

```json
{
  "url": "https://api.example.com/endpoint",
  "method": "POST",
  "headers": { "Authorization": "Bearer token" },
  "body": "{\"key\": \"{{contact.phone_number}}\"}"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Webhook endpoint URL |
| `method` | string | No | HTTP method (POST, GET, PUT, PATCH). Default: POST |
| `headers` | object | No | Custom HTTP headers |
| `body` | string | No | JSON request body template |

#### URL Config

```json
{
  "url": "https://crm.example.com/contact?phone={{contact.phone_number}}",
  "open_in_new_tab": true
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | URL to open |
| `open_in_new_tab` | boolean | No | Open in new tab (default: true) |

#### JavaScript Config

```json
{
  "code": "return { clipboard: contact.phone_number }"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `code` | string | Yes | JavaScript code to execute |

### Response

```json
{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Create Support Ticket",
    "icon": "ticket",
    "action_type": "webhook",
    "config": { ... },
    "is_active": true,
    "display_order": 0,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

## Update Custom Action

Update an existing custom action.

`PUT /api/custom-actions/{id}`

### Request Body

```json
{
  "name": "Updated Action Name",
  "is_active": false
}
```

All fields are optional. Only provided fields will be updated.

## Delete Custom Action

Delete a custom action.

`DELETE /api/custom-actions/{id}`

### Response

```json
{
  "status": "success",
  "data": {
    "status": "deleted"
  }
}
```

## Execute Custom Action

Execute a custom action for a specific contact.

`POST /api/custom-actions/{id}/execute`

### Request Body

```json
{
  "contact_id": "uuid"
}
```

### Response

The response varies based on action type:

#### Webhook Response

```json
{
  "status": "success",
  "data": {
    "success": true,
    "message": "Webhook executed successfully",
    "data": { ... },
    "toast": {
      "message": "Webhook executed successfully",
      "type": "success"
    }
  }
}
```

#### URL Response

```json
{
  "status": "success",
  "data": {
    "success": true,
    "message": "Opening URL",
    "redirect_url": "/api/custom-actions/redirect/token123"
  }
}
```

#### JavaScript Response

```json
{
  "status": "success",
  "data": {
    "success": true,
    "message": "JavaScript action executed",
    "data": {
      "code": "return { clipboard: contact.phone_number }",
      "context": {
        "contact": { ... },
        "user": { ... },
        "organization": { ... }
      }
    },
    "toast": {
      "message": "Action completed",
      "type": "success"
    }
  }
}
```

## Available Variables

Variables can be used in webhook URLs, bodies, and URL templates using `{{variable}}` syntax:

| Variable | Description |
|----------|-------------|
| `{{contact.id}}` | Contact's unique ID |
| `{{contact.phone_number}}` | Contact's phone number |
| `{{contact.name}}` | Contact's display name |
| `{{contact.profile_name}}` | Contact's WhatsApp profile name |
| `{{user.id}}` | Current user's ID |
| `{{user.name}}` | Current user's full name |
| `{{user.email}}` | Current user's email |
| `{{user.role}}` | Current user's role |
| `{{organization.id}}` | Organization's ID |
| `{{organization.name}}` | Organization's name |

## Available Icons

| Icon | Description |
|------|-------------|
| `ticket` | Support ticket |
| `user` | User/contact |
| `bar-chart` | Analytics/chart |
| `link` | Link |
| `phone` | Phone |
| `mail` | Email |
| `file-text` | Document |
| `external-link` | External link |
| `zap` | Quick action |
| `globe` | Web/globe |
| `code` | Code/script |

> **Note:** Custom actions are scoped to the organization. Each user in the organization will see the same set of custom actions in their chat interface.