# Setting Up Message Automations

## Objective

Configure automated messages that trigger when transport events occur — for example, emailing a customer when their shipment is delivered, or notifying your team when a transport order is delayed.

## Step 1: Create a Message Template

First, create a reusable message template:


```bash
curl -X POST https://api.otms.transportial.com/api/messageTemplate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Delivery confirmation",
    "subject": "Your shipment has been delivered",
    "body": "Dear customer, your transport order {{transportOrder.name}} has been successfully delivered."
  }'
```

**Response:**


```json
{
  "success": true,
  "message": "OK",
  "messageTemplate": {
    "id": "template-uuid",
    "name": "Delivery confirmation"
  }
}
```

## Step 2: Create a Message Automation

Set up the automation that uses this template:


```bash
curl -X POST https://api.otms.transportial.com/api/messageAutomation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Auto-notify customer on delivery",
    "enabled": true,
    "trigger": "transportOrder.status.realized",
    "messageTemplate": { "id": "template-uuid" }
  }'
```

**Response:**


```json
{
  "success": true,
  "message": "OK",
  "messageAutomation": {
    "id": "automation-uuid",
    "name": "Auto-notify customer on delivery",
    "enabled": true
  }
}
```

## Step 3: Browse Available Templates

Get pre-built templates to start from:


```bash
curl -X GET https://api.otms.transportial.com/api/messageAutomation-templates \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Step 4: Duplicate an Existing Automation

Clone an existing automation to create a variation:


```bash
curl -X POST "https://api.otms.transportial.com/api/messageAutomation/{automation-uuid}/duplicate" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Managing Automations

### List All Automations


```bash
curl -X GET "https://api.otms.transportial.com/api/messageAutomations/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Update an Automation


```bash
curl -X PUT https://api.otms.transportial.com/api/messageAutomation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": "automation-uuid",
    "enabled": false
  }'
```

### View Automation Tasks

See what messages have been sent by this automation:


```bash
curl -X GET "https://api.otms.transportial.com/api/messageAutomation/{automation-uuid}/tasks/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Managing Message Templates

### List Templates


```bash
curl -X GET "https://api.otms.transportial.com/api/messageTemplates/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Update a Template


```bash
curl -X PUT https://api.otms.transportial.com/api/messageTemplate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": "template-uuid",
    "subject": "Delivery confirmed - {{transportOrder.name}}",
    "body": "Dear {{customer.name}}, your shipment has arrived at the destination."
  }'
```

### Preview a Template as a Message

Generate a preview of how the template will look for a specific chat:


```bash
curl -X GET "https://api.otms.transportial.com/api/messageTemplate/{template-uuid}/message/{chatId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Common Automation Triggers

| Trigger | Description |
|  --- | --- |
| Transport order status change | When an order moves to requested, accepted, planned, realized, etc. |
| Consignment status change | When a consignment starts transit, is delivered, etc. |
| Trip lifecycle events | When a trip starts, finishes, or is delayed |
| Custom filter conditions | Using TQL to match specific criteria |


## Automation with Attachments

Automations can include file attachments — for example, attaching a CMR document or proof of delivery photo to the notification email. Attachments are pulled from the transport entity's document list automatically.

## Using Chat for Messaging

For real-time messaging between users:


```bash
# Create a chat
curl -X POST https://api.otms.transportial.com/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Shipment RTD-AMS discussion"
  }'

# Send a message
curl -X POST https://api.otms.transportial.com/api/chat/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "chatId": "chat-uuid",
    "content": "The driver is 15 minutes away from the pickup location."
  }'

# Get messages
curl -X GET "https://api.otms.transportial.com/api/chat/messages/{chatId}/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Translate a message
curl -X GET "https://api.otms.transportial.com/api/chat/message:translate/{messageId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Key Takeaways

- Message automations react to entity changes without any code
- Templates support variables that are filled with actual entity data
- Automations can include document attachments
- Use the duplicate endpoint to quickly create variations
- Monitor automation tasks to see delivery status