Triggers and Commands

Triggers are structured commands that an integration can return to Ticketz through a message or webhook response in order to perform actions on the current ticket.

Message format

Messages use this structure:

{
  "type": "text",
  "content": "message text",
  "mediaUrl": "https://example.com/file"
}

• type can be text, image, video, audio, gif, or document.
• content is used for text messages.
• mediaUrl is used for non-text media.
• expandMustaches (optional, boolean) — when true, the content of a text message is processed by the mustache helper before being sent, so ticket fields can be interpolated (for example Hello, ).

Ways to send commands

1. Text bubble inside Typebot

Typebot integrations can send one command at a time with a text bubble starting with # and followed by a JSON payload.

#{
  "queueId": 99
}

2. Webhook response payload

Webhook integrations can respond with:

• a single command
• a single message with an optional trigger
• an array of messages, each one with an optional trigger

Example:

[
  {
    "type": "text",
    "content": "One message"
  },
  {
    "type": "text",
    "content": "Another message",
    "trigger": { "action": "wait", "seconds": 2 }
  },
  {
    "type": "text",
    "content": "A message with a trigger",
    "trigger": { "closeTicket": true }
  }
]

3. Direct HTTP request to the backend

Typebot, Webhook, or any external system can call the backend directly if it has the authorization token.

• Endpoint: ${BACKEND_URL}/integrations/webhook
• Method: POST
• Header: Authorization: Bearer ${token}

The payload can be any format accepted in the webhook response method.

Available commands

Send a message

message can be a single message object or an array of message objects.

{
  "message": {
    "type": "text",
    "content": "message content"
  }
}

Send a message with menu options

{
  "message": {
    "type": "text",
    "content": "A message"
  },
  "action": "menu",
  "menuOptions": [{ "text": "Option 1" }, { "text": "Option 2" }]
}

Send a message with a URL button

Currently limited to channels that support that format, such as Notificamehub Official WhatsApp.

{
  "message": {
    "type": "text",
    "content": "Click the button below to learn more"
  },
  "action": "menu",
  "menuOptions": [
    {
      "text": "Ticketz PRO",
      "url": "https://pro.ticke.tz"
    }
  ]
}

Transfer to another queue

{
  "queueId": 99
}

If the new queue is not handled by a chatbot, Ticketz also removes the chatbot attribute.

Transfer to another queue and user

{
  "queueId": 99,
  "userId": 42
}

The ticket is accepted automatically and appears in the new user’s active service area.

End the integration session

{
  "action": "endSession"
}

Stop the chatbot

This is equivalent to endSession and exists for backward compatibility.

{
  "stopbot": true
}

Close the current ticket

{
  "closeTicket": true
}

Add an internal note to the ticket

{
  "action": "note",
  "message": {
    "content": "Note text"
  }
}

Update multiple ticket properties

{
  "action": "updateTicket",
  "ticketData": {
    "status": "pending",
    "userId": 42,
    "queueId": 99,
    "justClose": false,
    "annotation": "Escalated by automation"
  }
}

Allowed ticketData fields:

• status: pending, open, or closed
• userId: transfer to another user
• queueId: transfer to another queue
• justClose: close without other transition rules
• annotation: add a note when transferring

Wait for a number of seconds

Effective only inside an array of commands.

{
  "action": "wait",
  "seconds": 2
}

Ping

Forces Ticketz to answer automatically with pong, which can help preserve ordering in Typebot.

{
  "action": "ping"
}

Post a request to an external webhook

Sends a POST request to the given url with the current ticket data (the same output produced by ShowTicketService) as the JSON body. The response is interpreted as commands and processed in a nested way, so the webhook can reply with any of the commands documented here.

• timeout (optional, number) — timeout in seconds. Defaults to 5.
• Errors calling the webhook are logged but do not interrupt the execution.
• A nested postRequest inside the response is allowed, but its own response will not be processed. This caps the recursion at one level, preventing unbounded chains of webhooks calling each other.

{
  "action": "postRequest",
  "url": "https://example.com/hook",
  "timeout": 10
}

Add a tag to the ticket

If advanceOnly is true, a funnel tag cannot replace another tag from the same funnel that is already further ahead.

{
  "action": "addTag",
  "tagId": 99,
  "advanceOnly": true
}

Remove a tag from the ticket

{
  "action": "removeTag",
  "tagId": 99
}

Clear all ticket tags

{
  "action": "clearTags"
}

Add a tag to the contact

{
  "action": "addContactTag",
  "tagId": 99,
  "advanceOnly": true
}

Remove a tag from the contact

{
  "action": "removeContactTag",
  "tagId": 99
}

Clear all contact tags

{
  "action": "clearContactTags"
}

For ready-made payload samples, visit Example files.