Event Tasks
Overview
An event task waits for something to happen on your hotline and then does something about it. A caller leaves a message and you get an email with the recording attached. A transcription finishes and the text is emailed on. A conference recording is saved into an audio player automatically. Unlike Scheduled Tasks, which run on a clock, these run the moment the event occurs.
Find them in the sidebar under Advanced → Tasks. (The Advanced group is collapsed by default; click it to open.)
How It Works
Every task is one sentence made of three parts:
- A source — the audio player, forward call, conference, or merchant being watched.
- An event — what has to happen on it.
- An action — what to do when it happens.
The actions on offer change with the source and the event, so you can only build combinations that make sense.
Task Information
- Task Name — required. A name that identifies this task for you.
Trigger Configuration
-
Trigger Source — required. One of:
Source What it watches Library an audio player, which is where message boxes save their messages Message box a message box itself — fires for every finished message, even when the box saves nothing Transfer to Number a forward call block Conference a conference room Merchant a payee taking card payments -
Select Item — required. The specific audio player, forward call, conference, or merchant.
-
Trigger Event — required, and the choices depend on the source:
Source Events Library new library Recording · transcription completed Message box new message recorded (saved or not) Transfer to Number started new call Conference new conference recording Merchant new payment received
Action Configuration
Action to Perform is required, and the list depends on the source and event you picked:
| Source | Event | Actions available |
|---|---|---|
| Library | new library Recording | send email with recording · transcript · send to a URL |
| Message box | new message recorded (saved or not) | send email with recording · send to a URL |
| Library | transcription completed | send email with transcript · send to a URL |
| Transfer to Number | started new call | send email · send to a URL |
| Conference | new conference recording | send email with recording · create a library recording · send to a URL |
| Merchant | new payment received | credit callmagic balance · send to a URL |
What each one does:
- send email with recording — emails the new recording to the addresses you list.
- transcript — sends the new recording off to be transcribed. When the transcription comes back it fires the transcription completed event, which is what you hang the next task on. Transcription is a billed feature; see Billing, Plans & Add-ons.
- send email with transcript — emails the finished text.
- send email — emails you that a transferred call has started.
- create a library recording — saves the conference recording into an audio player of your choosing, so callers can listen to it later.
- credit callmagic balance — adds the payment to a CallMagic balance.
- On a Message box, the event fires for every finished message, whether or not the box saves into an audio player. A box with no player keeps nothing, so a task here is the only place the message goes: email it, or send it to a URL. To transcribe a message it has to be saved into a player, so use the player's events for that.
- send to a URL — calls a web address of yours with the details of the event, so your own system, a CRM, a membership site, a Google Sheet or an automation tool (Make, Zapier, n8n) is told the moment it happens. See Sending to a URL below.
Action Options
These appear only for the actions that need them:
- Email Recipients — required for send email with recording, send email with transcript, and send email. A comma separated list, for example
office@example.com, gabbai@example.com. - Include the caller's phone number — only for send email with recording. Adds the number the message was left from, when the caller ID is known.
- Target Library — required for create a library recording. "Conference recordings will be saved to this library."
- CallMagic API Token — required for credit callmagic balance. A personal access token from your CallMagic account, entered as a hidden password you can reveal. The credited balance lands on the user that owns this token.
Sending to a URL
The send to a URL action turns any event into an HTTP request to a system of yours. You build the request the way you would in Postman or Twilio Studio, and placeholders fill in the details of the event.
Request
- Method — POST (default), GET, PUT, PATCH or DELETE.
- URL — must start with
https://. Placeholders work here too, for examplehttps://hook.example.com/in?caller={{caller_number}}. Private and local addresses are refused. - Content type — JSON (default), form (urlencoded) or raw text.
Authentication
None, a Bearer token, Basic (enter user:password) or an API key header where you name the header, for example X-API-KEY. The value is stored encrypted and never shown again in full. Do not put credentials into the URL.
Headers
Add as many as you need, for example Accept: application/json. Values accept placeholders.
Body
Two ways, pick one:
- Fields — one row per key.
transcript={{transcript}},phone={{caller_number}},source=hotline. Dots nest the key:member.phonebecomes{"member": {"phone": "..."}}. A value that is only a placeholder keeps its type, so{{duration}}is sent as a number and{{keywords}}as a list. - Raw template — write the JSON or text yourself and drop placeholders in. For JSON the values are escaped for you, so a transcript with quotes cannot break it.
GET requests send no body; put what you need into the URL.
Placeholders
Write them as {{name}}. The Placeholders panel on the task lists exactly what the chosen event offers; click one to copy it. Every event has:
| Placeholder | Meaning |
|---|---|
{{event}} / {{event_at}} |
The event name and when it happened (UTC) |
{{hotline_name}} / {{account_uuid}} / {{task_name}} |
Which hotline and task sent it; the account ID is the one on your Settings page |
{{caller_number}} |
The caller's number, digits only |
{{caller_name}} / {{contact_id}} / {{contact_email}} / {{contact_labels}} |
Filled when the number matches one of your contacts |
Per event:
| Event | Extra placeholders |
|---|---|
| new library Recording | recording_id, recording_name, recording_url, duration, library_id, library_name, recorded_at |
| new message recorded | recording_url, duration, recorded_at, box_id, box_name, saved (true/false), plus recording_id, library_id, library_name when saved |
| transcription completed | the above plus transcript, summary, keywords, word_count, transcribed_at |
| new conference recording | recording_id, recording_url, duration, conference_id, conference_name, call_sid, recorded_at |
| started new call | forward_id, forward_name, dialed_number |
| new payment received | amount, currency, card_brand, card_last_four, confirmation_code, charge_id, call_sid, paid_at |
Delivery
- Attempts — up to 5. Network errors and 5xx answers are retried with growing pauses (30 s, 2 min, 10 min, 30 min). A 4xx answer means the request itself is wrong, so it is not retried.
- Timeout — 5 to 30 seconds.
- Email me when it keeps failing — one email per task per hour at most, with the reason.
The task list shows the Last run: ok or failed, the HTTP status, and when. Hover for the error. Open the task and switch to the Runs tab for the full history: every attempt with its status, HTTP code, how long it took, the request that was sent (header names only, never your secrets), the response, and the event values it had. Runs are kept for 90 days, at most 200 per task. On the task's edit page, Send test request sends one request with sample values so you can see what your system receives before the first real event; test runs are marked as such.
Tasks the builder creates for you
Some tasks appear that you never created. That is normal, and it is the message box doing it for you.
When you set Email each new message to on a Message box (in the ⚙ panel on My Hotline, or on the Message Box page), the app creates a task behind the scenes:
- Trigger Source Library, pointed at the audio player the box saves into
- Trigger Event new library Recording
- Action send email with recording, with your addresses and the Include the caller's phone number setting
- Named "Email new messages — " plus the box’s name
If you change the addresses, that task is updated. If you clear them, it is deleted. If you point the message box at a different audio player, the task moves with it. You can open it in this list and adjust it like any other task, but the simplest place to change it stays the message box itself.
Managing tasks
The list shows Task Name (with the name of the source underneath), Trigger Source, Trigger Event, and Action, newest first.
It can be filtered by:
- Trigger Source — Library, Transfer to Number, Conference, Merchant
- Trigger Event — New Recording, Transcription Completed, New Call Started, New Conference Recording, New Payment Received
- Action — Email + Recording, Email + Transcript, Send Email, Transcribe, Create Library Recording, Credit CallMagic Balance
Created, Last Updated, and Deleted are hidden columns you can switch on from the column menu.
Deleting a task is a soft delete, so nothing is lost outright. The bulk actions menu holds Delete, Force delete, and Restore. Unlike Scheduled Tasks, this list has no Trashed filter, so a deleted task drops out of view; ask support if you need one brought back.
Common Patterns
- Voicemail to your inbox. The easiest route is the Email each new message to field on the message box. Do it there and the task is made for you.
- Voicemail you can read. Two tasks on the same audio player: one on new library Recording running transcript, and one on transcription completed running send email with transcript. Now every message arrives as text.
- Keep your conferences. On the conference, new conference recording → create a library recording with a Target Library called something like "Conference recordings". Point a menu key at that player and anyone can listen back.
- Know when the office line rings. On the forward call, started new call → send email.
Tips
- One source can have several tasks. They all run.
- The same audio player can be watched by more than one task, which is exactly how the transcribe-then-email pair works.
- Make sure the Select Item really is the audio player your message box saves into. If messages land elsewhere, no event fires.
- For anything based on a time rather than an event, use Scheduled Tasks.