Skip to content
/
Setting Up Message Automa...
Last updated

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:

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:

{
  "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:

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:

{
  "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:

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:

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

Managing Automations

List All Automations

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

Update an Automation

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:

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

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

Update a Template

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:

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

Common Automation Triggers

TriggerDescription
Transport order status changeWhen an order moves to requested, accepted, planned, realized, etc.
Consignment status changeWhen a consignment starts transit, is delivered, etc.
Trip lifecycle eventsWhen a trip starts, finishes, or is delayed
Custom filter conditionsUsing 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:

# 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
Previous page
Next page