Undo or send a held message now
curl --request POST \
--url https://app.tuco.ai/api/unibox/held-reply \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"messageId": "<string>",
"action": "<string>",
"passFifo": true
}
'import requests
url = "https://app.tuco.ai/api/unibox/held-reply"
payload = {
"messageId": "<string>",
"action": "<string>",
"passFifo": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({messageId: '<string>', action: '<string>', passFifo: true})
};
fetch('https://app.tuco.ai/api/unibox/held-reply', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.tuco.ai/api/unibox/held-reply",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'messageId' => '<string>',
'action' => '<string>',
'passFifo' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/unibox/held-reply"
payload := strings.NewReader("{\n \"messageId\": \"<string>\",\n \"action\": \"<string>\",\n \"passFifo\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.tuco.ai/api/unibox/held-reply")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"messageId\": \"<string>\",\n \"action\": \"<string>\",\n \"passFifo\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/unibox/held-reply")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"messageId\": \"<string>\",\n \"action\": \"<string>\",\n \"passFifo\": true\n}"
response = http.request(request)
puts response.read_body{
"ok": true,
"state": "<string>",
"fifo": {},
"status": "<string>"
}Messages
Undo or send a held message now
Cancel a reply in its Undo window, or send a held message now, optionally skipping the per-contact queue (passFifo).
POST
/
api
/
unibox
/
held-reply
Undo or send a held message now
curl --request POST \
--url https://app.tuco.ai/api/unibox/held-reply \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"messageId": "<string>",
"action": "<string>",
"passFifo": true
}
'import requests
url = "https://app.tuco.ai/api/unibox/held-reply"
payload = {
"messageId": "<string>",
"action": "<string>",
"passFifo": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({messageId: '<string>', action: '<string>', passFifo: true})
};
fetch('https://app.tuco.ai/api/unibox/held-reply', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.tuco.ai/api/unibox/held-reply",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'messageId' => '<string>',
'action' => '<string>',
'passFifo' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/unibox/held-reply"
payload := strings.NewReader("{\n \"messageId\": \"<string>\",\n \"action\": \"<string>\",\n \"passFifo\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.tuco.ai/api/unibox/held-reply")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"messageId\": \"<string>\",\n \"action\": \"<string>\",\n \"passFifo\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/unibox/held-reply")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"messageId\": \"<string>\",\n \"action\": \"<string>\",\n \"passFifo\": true\n}"
response = http.request(request)
puts response.read_body{
"ok": true,
"state": "<string>",
"fifo": {},
"status": "<string>"
}The Try it panel runs against production (
https://app.tuco.ai) with the key you paste into it.
There is no sandbox: send_now sends a real message, and cancel cancels a real one.What this endpoint does
A message can be held before it goes out:- In its Undo window. A reply sent with an Undo delay, or an Autopilot reply your workspace holds for Undo.
- In the per-contact queue. It waits behind an earlier message to the same contact on the same line. See Message order (FIFO) and Send now.
action | What happens |
|---|---|
cancel | The message never goes out. If it reserved a daily-limit slot, the slot is given back. |
send_now | The message goes now instead of at the end of its Undo window. |
send_now + passFifo: true | It also skips the queue: it goes even though an earlier message to the same contact is still waiting. |
Authentication
Authorization: Bearer tuco_xxxxxxxxxxxxx
Request body
The id of the held message (the
_id returned when you sent it, or from GET /api/messages).Only with
send_now. Lets this one message skip the per-contact queue. It also works on a message the queue
is holding after its Undo window ended (rescheduleReason: "fifo:serial_lock_blocked"). It is refused on a
first message: if nothing has been delivered to this contact on this line yet, the message keeps waiting and
the response says fifo.passFifoRefused: "first_message".Example
curl -X POST "https://app.tuco.ai/api/unibox/held-reply" \
-H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "messageId": "6b02fb399a3f70b73d69cf2d", "action": "send_now", "passFifo": true }'
Responses
Cancelled
{ "ok": true, "state": "cancelled" }
Sending now
{ "ok": true, "state": "sending" }
Send now + passFifo
{
"ok": true,
"state": "sending",
"fifo": {
"blocked": false,
"behind": null,
"behindDueAt": null,
"passFifo": true,
"checked": true
}
}
passFifo refused (first message)
{
"ok": true,
"state": "held",
"fifo": {
"blocked": true,
"behind": "6b02fb2a9a3f70b73d69cf21",
"behindDueAt": null,
"passFifo": true,
"passFifoRefused": "first_message",
"checked": true
}
}
Too late
{ "ok": false, "state": "too_late", "status": "sent" }
cancelled, sending (it goes now), held (it still waits behind an earlier message), or too_late
(it was already being sent, or already sent).Only when
passFifo was sent. blocked: still waiting behind an earlier message. behind: that message’s id.
behindDueAt: when it is due, if it is planned for a set time. passFifoRefused: first_message when skipping
was refused. checked: false if the check could not run (then blocked is unknown).Errors
| Status | When |
|---|---|
400 | messageId missing or not a valid id, or action is not cancel / send_now. |
401 | Missing or invalid API key. |
404 | Reply not found: no held message with this id that you can act on in this workspace. |
Cancel and send now are atomic: they only act while the message is still waiting. If Tuco has already started
sending it, the answer is
state: "too_late" and the message goes out (or went).