Bot templates
Ask Fluid to message a customer
With a bot’s run login: ask Fluid to message the customer of a touch the run was given, with one allowed lever and channel and typed slot references. The request declares customer_outreach.create (action class message_customer), so the run’s grant and the owner’s autonomy mode decide first. Fluid then checks, in order, that the touch is in the treatment arm and unused, the playbook is on, the lever and channel are allowed, the customer still qualifies, the company can send from its own identity, and the customer has not opted out, is not blocked, has consent where needed and had no bot message within the playbook’s frequency. Shadow mode records the choice and sends nothing; outside the playbook’s quiet hours in the customer’s time zone the message is scheduled. Fluid renders the message from the template’s reviewed copy and adds every link. Send an Idempotency-Key header; a repeat answers the first outcome. A retry of an approved call that sent nothing runs again on the approval it used, only with the identical body and the same Fluid-Bot-Approval; any other body needs its own approval.
POST
/
api
/
company
/
v2026-10
/
bot-runs
/
current
/
outreach
Ask Fluid to message a customer
curl --request POST \
--url https://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"outreach": {
"playbook": "declined_subscription",
"touch_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90",
"lever": "update_payment",
"channel": "email"
}
}
'import requests
url = "https://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach"
payload = { "outreach": {
"playbook": "declined_subscription",
"touch_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90",
"lever": "update_payment",
"channel": "email"
} }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
outreach: {
playbook: 'declined_subscription',
touch_id: '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90',
lever: 'update_payment',
channel: 'email'
}
})
};
fetch('https://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach', 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://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach",
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([
'outreach' => [
'playbook' => 'declined_subscription',
'touch_id' => '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90',
'lever' => 'update_payment',
'channel' => 'email'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$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://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach"
payload := strings.NewReader("{\n \"outreach\": {\n \"playbook\": \"declined_subscription\",\n \"touch_id\": \"0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90\",\n \"lever\": \"update_payment\",\n \"channel\": \"email\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"outreach\": {\n \"playbook\": \"declined_subscription\",\n \"touch_id\": \"0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90\",\n \"lever\": \"update_payment\",\n \"channel\": \"email\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"outreach\": {\n \"playbook\": \"declined_subscription\",\n \"touch_id\": \"0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90\",\n \"lever\": \"update_payment\",\n \"channel\": \"email\"\n }\n}"
response = http.request(request)
puts response.read_body{
"outcome": "requested",
"touch": {
"id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90",
"bot_id": "0192f3c4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
"playbook_key": "declined_subscription",
"subject_type": "Commerce::Subscription",
"subject_id": "481",
"episode_key": "481:1761091200",
"arm": "treatment",
"status": "requested",
"refusal_reason": null,
"lever": "update_payment",
"channel": "email",
"message_type": "we_bot_subscription_save",
"slots": {},
"run_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a95",
"approval_id": null,
"delivery_state": "sent",
"provider_message_id": "0100019a-ses",
"comms_event_id": null,
"click_count": null,
"template_version_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a92",
"assigned_at": "2026-10-22T15:32:08Z",
"scheduled_for": null,
"requested_at": "2026-10-22T15:32:08Z",
"sent_at": null,
"delivered_at": null,
"first_opened_at": null,
"bounced_at": null,
"complained_at": null,
"first_clicked_at": null,
"window_ends_at": "2026-11-05T15:32:08Z"
},
"status": 202,
"meta": {
"request_uuid": "7e2c9b41-3f8a-4d15-b6e0-9a4c21d7f583",
"timestamp": "2026-10-22T15:32:08Z"
}
}{
"message": "Invalid credentials."
}{
"message": "Only a running bot can call this"
}{
"error": {
"message": "Touch not found",
"details": {
"type": "touch_not_found"
}
},
"status": 404,
"meta": {
"request_uuid": "7e2c9b41-3f8a-4d15-b6e0-9a4c21d7f583",
"timestamp": "2026-10-22T15:32:08Z"
}
}{
"error": {
"message": "This customer is held out; the bot may not message them",
"details": {
"type": "held_out"
}
},
"status": 409,
"meta": {
"request_uuid": "7e2c9b41-3f8a-4d15-b6e0-9a4c21d7f583",
"timestamp": "2026-10-22T15:32:08Z"
}
}{
"error": {
"message": "The customer opted out of bot messages from this store",
"details": {
"type": "refused"
}
},
"status": 422,
"meta": {
"request_uuid": "7e2c9b41-3f8a-4d15-b6e0-9a4c21d7f583",
"timestamp": "2026-10-22T15:32:08Z"
}
}Authorizations
A bot's run login, minted for one run.
Headers
Names this call; at most 255 characters.
Maximum string length:
255Body
application/json
Show child attributes
Show child attributes
Response
The touch, requested, scheduled or shadowed; outcome says which.
⌘I
Ask Fluid to message a customer
curl --request POST \
--url https://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"outreach": {
"playbook": "declined_subscription",
"touch_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90",
"lever": "update_payment",
"channel": "email"
}
}
'import requests
url = "https://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach"
payload = { "outreach": {
"playbook": "declined_subscription",
"touch_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90",
"lever": "update_payment",
"channel": "email"
} }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
outreach: {
playbook: 'declined_subscription',
touch_id: '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90',
lever: 'update_payment',
channel: 'email'
}
})
};
fetch('https://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach', 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://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach",
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([
'outreach' => [
'playbook' => 'declined_subscription',
'touch_id' => '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90',
'lever' => 'update_payment',
'channel' => 'email'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$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://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach"
payload := strings.NewReader("{\n \"outreach\": {\n \"playbook\": \"declined_subscription\",\n \"touch_id\": \"0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90\",\n \"lever\": \"update_payment\",\n \"channel\": \"email\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"outreach\": {\n \"playbook\": \"declined_subscription\",\n \"touch_id\": \"0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90\",\n \"lever\": \"update_payment\",\n \"channel\": \"email\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fluid.app/api/company/v2026-10/bot-runs/current/outreach")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"outreach\": {\n \"playbook\": \"declined_subscription\",\n \"touch_id\": \"0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90\",\n \"lever\": \"update_payment\",\n \"channel\": \"email\"\n }\n}"
response = http.request(request)
puts response.read_body{
"outcome": "requested",
"touch": {
"id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a90",
"bot_id": "0192f3c4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
"playbook_key": "declined_subscription",
"subject_type": "Commerce::Subscription",
"subject_id": "481",
"episode_key": "481:1761091200",
"arm": "treatment",
"status": "requested",
"refusal_reason": null,
"lever": "update_payment",
"channel": "email",
"message_type": "we_bot_subscription_save",
"slots": {},
"run_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a95",
"approval_id": null,
"delivery_state": "sent",
"provider_message_id": "0100019a-ses",
"comms_event_id": null,
"click_count": null,
"template_version_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a92",
"assigned_at": "2026-10-22T15:32:08Z",
"scheduled_for": null,
"requested_at": "2026-10-22T15:32:08Z",
"sent_at": null,
"delivered_at": null,
"first_opened_at": null,
"bounced_at": null,
"complained_at": null,
"first_clicked_at": null,
"window_ends_at": "2026-11-05T15:32:08Z"
},
"status": 202,
"meta": {
"request_uuid": "7e2c9b41-3f8a-4d15-b6e0-9a4c21d7f583",
"timestamp": "2026-10-22T15:32:08Z"
}
}{
"message": "Invalid credentials."
}{
"message": "Only a running bot can call this"
}{
"error": {
"message": "Touch not found",
"details": {
"type": "touch_not_found"
}
},
"status": 404,
"meta": {
"request_uuid": "7e2c9b41-3f8a-4d15-b6e0-9a4c21d7f583",
"timestamp": "2026-10-22T15:32:08Z"
}
}{
"error": {
"message": "This customer is held out; the bot may not message them",
"details": {
"type": "held_out"
}
},
"status": 409,
"meta": {
"request_uuid": "7e2c9b41-3f8a-4d15-b6e0-9a4c21d7f583",
"timestamp": "2026-10-22T15:32:08Z"
}
}{
"error": {
"message": "The customer opted out of bot messages from this store",
"details": {
"type": "refused"
}
},
"status": 422,
"meta": {
"request_uuid": "7e2c9b41-3f8a-4d15-b6e0-9a4c21d7f583",
"timestamp": "2026-10-22T15:32:08Z"
}
}