Tools
The server registers 16 tools. Each one calls one SDK method with the server’s API key, so the key’s scopes decide which tools work. A tool the key can’t use returns SMSFabric error 403 (forbidden) to the assistant rather than failing silently.
Every tool answers with a one-line summary for the assistant, followed by the full JSON response. Errors come back as a tool error with the HTTP status, the code, the detail and any field errors, so the assistant can explain or fix the request.
| Tool | Scope | Annotation |
|---|---|---|
send_sms |
messages:send |
destructive (sends) |
list_messages |
messages:read |
read-only |
get_message |
messages:read |
read-only |
send_verification |
verify:send |
sends |
check_verification |
verify:check |
uses an attempt |
list_devices |
devices:read |
read-only |
find_contacts |
contacts:read |
read-only |
add_contact |
contacts:manage |
writes |
list_campaigns |
campaigns:read |
read-only |
get_campaign |
campaigns:read |
read-only |
create_campaign |
campaigns:manage |
writes a draft |
estimate_campaign |
campaigns:read |
read-only |
start_campaign |
campaigns:manage, messages:send |
destructive |
pause_campaign |
campaigns:manage |
writes |
resume_campaign |
campaigns:manage |
writes |
cancel_campaign |
campaigns:manage |
destructive |
Phone numbers are always E.164: a +, the country code and the number, 8 to 16 characters in all (+201001234567).
Messages
Section titled “Messages”send_sms
Section titled “send_sms”Sends one text to one number or up to 100 through your gateway phones. A blacklisted number comes back with status blocked. With an sf_test_ key nothing reaches a real phone.
The tool is annotated readOnlyHint: false, destructiveHint: true and openWorldHint: true: a sent SMS can’t be recalled, so clients that honour annotations ask before every call. Its description tells the assistant to make up one idempotencyKey per message it means to send and to reuse that key if it calls send_sms again after a timeout or error. SMSFabric then returns the original messages instead of sending a second time.
| Input | Type | Required | Constraints |
|---|---|---|---|
to |
string or string[] | yes | E.164, or a list of 1 to 100 E.164 numbers |
body |
string | yes | 1 to 1,600 characters |
deviceId |
string | no | Send from this phone (dev_…) |
simId |
string | no | Send from this SIM (sim_…) |
poolId |
string | no | Send through this pool (pool_…) |
idempotencyKey |
string | no | 1 to 255 characters, unique per intended send. Reuse it when retrying the same send. Without it, only the client’s own automatic retries are protected |
Returns one line per message (msg_… → +201001234567: queued) and the messages as JSON.
Example prompt: “Text +201001234567: Your table for 4 is ready at 8 pm.”
list_messages
Section titled “list_messages”Lists recent messages, newest first.
| Input | Type | Required | Constraints |
|---|---|---|---|
direction |
enum | no | outbound or inbound |
status |
enum | no | queued, routed, sending, sent, delivered, failed, blocked, received |
q |
string | no | Digits of a phone number: 3 to 15, with an optional leading +. Matches any part of to or from, so 4567 finds numbers ending in 4567. Names aren’t accepted; use find_contacts for those |
limit |
integer | no | 1 to 200. Default 20 |
cursor |
string | no | The nextCursor from the previous call |
Returns one line per message (time, direction, number, status and the first 80 characters) and the page as JSON, with nextCursor when there is more.
Example prompt: “Show me the messages that failed today.”
get_message
Section titled “get_message”Gets one message with its delivery timeline.
| Input | Type | Required | Constraints |
|---|---|---|---|
id |
string | yes | A message id, msg_ followed by lowercase letters and digits |
Returns the status and the event chain (queued → routed → sent → delivered), then the message as JSON.
Example prompt: “Was msg_q8v2k4n6p1r3t5w7y9z0b2c4 delivered?”
Verify
Section titled “Verify”send_verification
Section titled “send_verification”Sends a one-time code to check that someone controls a phone number. SMSFabric generates the code and never returns it; the assistant must ask the person to read it back. A new send to the same number replaces the pending code. At most 3 codes per number every 10 minutes, and the country must be allowed in the portal under Verify settings.
| Input | Type | Required | Constraints |
|---|---|---|---|
to |
string | yes | E.164 |
locale |
enum | no | en or ar. Default en |
codeLength |
integer | no | 4 to 10 digits. Default 6 |
ttlSeconds |
integer | no | 60 to 1,800. Default 600 |
Returns the verification id (ver_…), the masked number, its status and when it expires.
Example prompt: “Send a verification code in Arabic to +201001234567.”
check_verification
Section titled “check_verification”Checks the code the person received. Every call uses one of the 5 attempts, so the assistant should only check a code the person gave it.
| Input | Type | Required | Constraints |
|---|---|---|---|
id |
string | yes | The ver_… id from send_verification |
code |
string | yes | 4 to 10 digits |
Returns approved (the number is verified), pending with the attempts left (wrong code), denied (5 wrong codes) or expired.
Example prompt: “She says the code is 482913.”
Phones
Section titled “Phones”list_devices
Section titled “list_devices”Lists your gateway phones. It takes no input.
Returns one line per phone (id, name, online, offline or disabled, battery and number of SIMs) and the phones as JSON, with signal, network and SIM details.
Example prompt: “Are all our gateway phones online? Which ones are below 20% battery?”
Contacts
Section titled “Contacts”find_contacts
Section titled “find_contacts”Searches the address book.
| Input | Type | Required | Constraints |
|---|---|---|---|
q |
string | no | Up to 120 characters. A name or email (contains), a full E.164 number, or its last 4 digits |
tag |
string | no | Up to 40 characters |
groupId |
string | no | grp_ followed by lowercase letters and digits |
optedOut |
boolean | no | true: only opted-out contacts; false: only reachable ones |
limit |
integer | no | 1 to 200. Default 20 |
cursor |
string | no | The nextCursor from the previous call |
Returns one line per contact (id, number, name, tags and [opted out]) and the page as JSON.
Example prompt: “Find the contact whose number ends in 4567.”
add_contact
Section titled “add_contact”Adds a contact, one per number. A number that already exists returns 409 contact_exists.
| Input | Type | Required | Constraints |
|---|---|---|---|
phone |
string | yes | E.164 |
firstName |
string | no | Up to 120 characters |
lastName |
string | no | Up to 120 characters |
email |
string | no | A valid email, up to 254 characters |
tags |
string[] | no | Up to 20 tags of up to 40 characters each |
consentSource |
enum | no | Where the person agreed to receive messages: web_form, import, api, in_person, paper, sms_keyword (they texted a keyword such as START), other |
Returns the new contact’s id and number, and the contact as JSON.
Example prompt: “Add Sara Adel, +201001234568, tagged vip. She signed up on our website.”
Campaigns
Section titled “Campaigns”Campaign ids are cmp_ followed by lowercase letters and digits. A campaign runs draft → running ⇄ paused → completed, or ends canceled.
list_campaigns
Section titled “list_campaigns”Lists campaigns, newest first, with progress.
| Input | Type | Required | Constraints |
|---|---|---|---|
status |
enum | no | draft, scheduled, running, paused, completed, canceled |
limit |
integer | no | 1 to 200. Default 20 |
cursor |
string | no | The nextCursor from the previous call |
Returns one progress line per campaign: id, name, status, sent of recipients, delivered, failed, skipped, pending and the ETA.
Example prompt: “Which campaigns are running right now?”
get_campaign
Section titled “get_campaign”One campaign with live progress, or its report.
| Input | Type | Required | Constraints |
|---|---|---|---|
id |
string | yes | cmp_… |
report |
boolean | no | true adds skips by reason, failures by error code and counts per phone |
Returns the progress line, and with report the skip and failure breakdown, then the JSON.
Example prompt: “How did the November offers campaign do? Why were people skipped?”
create_campaign
Section titled “create_campaign”Creates a draft. Nothing is sent until start_campaign. The audience is the contacts in any of the groups or with any of the tags. The body may use {{first_name}}, {{last_name}} and {{custom.<key>}}, with fallbacks such as {{first_name|there}}; the description asks the assistant to include opt-out wording such as “Reply STOP to opt out”.
| Input | Type | Required | Constraints |
|---|---|---|---|
name |
string | yes | 1 to 120 characters |
body |
string | no | 1 to 1,600 characters. Give exactly one of body and templateId |
templateId |
string | no | tpl_ followed by lowercase letters and digits. Give exactly one of body and templateId |
groupIds |
string[] | no | Up to 20 grp_… ids |
tags |
string[] | no | Up to 20 tags of up to 40 characters each |
poolId |
string | no | Send through this pool |
ratePerMinute |
integer | no | 1 to 6,000 across all phones. Default 120 |
hourlyCap |
integer | no | 1 to 360,000 recipients per clock hour in the campaign time zone |
dailyCap |
integer | no | 1 to 8,640,000 recipients per calendar day; not below hourlyCap |
quietHoursStart |
string | no | HH:MM (24-hour) in each recipient’s local time, e.g. 21:00 |
quietHoursEnd |
string | no | HH:MM, e.g. 09:00 |
scheduledAt |
string | no | ISO 8601 date and time with an offset, e.g. 2026-12-01T09:00:00+02:00. start_campaign then schedules the campaign for that time instead of starting it now |
Give quietHoursStart and quietHoursEnd together or not at all. The tool returns an error, without calling the API, when only one is given or when body and templateId are both given or both missing.
Returns the draft’s id with a reminder to estimate before starting, and the campaign as JSON.
Example prompt: “Draft a campaign called Weekend offer to the vip tag: Hi {{first_name|there}}, 20% off this weekend. Reply STOP to opt out. No messages between 9 pm and 9 am.”
estimate_campaign
Section titled “estimate_campaign”What a draft or scheduled campaign will do before it starts: recipients after opt-outs and the blacklist, total segments, the effective rate given the throttle and phone capacity, how many recipients wait for quiet hours, the duration and any warnings.
| Input | Type | Required | Constraints |
|---|---|---|---|
id |
string | yes | cmp_… |
Returns a summary such as “1,240 recipients (12 opted out, 3 blacklisted skipped), 1,240 segments, about 11 min at 120/min” and the estimate as JSON.
Example prompt: “How long would that campaign take, and how many people would get it?”
start_campaign
Section titled “start_campaign”Starts a draft now, or at its scheduled time. It sends real SMS to every recipient with a live key. The tool is annotated destructiveHint: true, and its description tells the assistant to confirm with you and run estimate_campaign first.
| Input | Type | Required | Constraints |
|---|---|---|---|
id |
string | yes | cmp_… |
Returns the progress line with status running (or scheduled).
Example prompt: “The estimate looks right. Start the Weekend offer campaign.”
pause_campaign
Section titled “pause_campaign”Pauses a running campaign. Messages already handed to a phone still go out; nothing new is claimed until it resumes.
| Input | Type | Required | Constraints |
|---|---|---|---|
id |
string | yes | cmp_… |
Returns the progress line with status paused.
Example prompt: “Pause the Weekend offer campaign, there’s a typo.”
resume_campaign
Section titled “resume_campaign”Resumes a paused campaign. The throttle restarts from now, so there is no burst.
| Input | Type | Required | Constraints |
|---|---|---|---|
id |
string | yes | cmp_… |
Returns the progress line with status running.
Example prompt: “Resume the campaign.”
cancel_campaign
Section titled “cancel_campaign”Cancels a scheduled, running or paused campaign for good. Pending recipients are skipped and messages no phone has taken yet are blocked. It cannot be undone. The tool is annotated destructiveHint: true.
| Input | Type | Required | Constraints |
|---|---|---|---|
id |
string | yes | cmp_… |
Returns the progress line with status canceled.
Example prompt: “Cancel the Weekend offer campaign completely.”