sandbox-twilio

name	sandbox-twilio
description	Send SMS and WhatsApp messages and look up numbers from a Code node or CodeAct action, with NodeTool's Twilio request builder running on the host

Twilio in the sandbox

Specifier: @nodetool-ai/sandbox-twilio. Import it at the top of the body.

Twilio is HTTP Basic auth over form-encoded bodies, on a URL that buries the account SID in the path. None of that is hard; all of it is easy to get wrong once, and the failure is a 401 that names nothing.

Nothing here sends a request. request builds one; the guest's own fetch sends it, under the run's fetch cap and SSRF guard.

request

import { request } from "@nodetool-ai/sandbox-twilio";

const accountSid = await nodetool.secrets.get("TWILIO_ACCOUNT_SID");
const authToken = await nodetool.secrets.get("TWILIO_AUTH_TOKEN");

const req = await request({
  accountSid, authToken,
  path: "Messages.json",
  method: "POST",
  params: { To: inputs.to, From: inputs.from, Body: inputs.text }
});
const res = await fetch(req.url, req);
if (!res.ok) throw new Error(`Twilio: ${res.json.message ?? res.status}`);
return { sid: res.json.sid, status: res.json.status };

Options: accountSid and authToken (required), path (required), method (default GET), params, host (default api.twilio.com), query.

params become the form body on a write and the query string on a read.

A path without a leading slash is an Account resource and lands under /2010-04-01/Accounts/<sid>/. One with a leading slash is used as written, which is how the other products are reached.

WhatsApp

Same endpoint; the numbers carry a whatsapp: prefix.

const req = await request({
  accountSid, authToken, path: "Messages.json", method: "POST",
  params: {
    To: `whatsapp:${inputs.to}`,
    From: `whatsapp:${inputs.from}`,
    Body: inputs.text
  }
});

Reading messages

const req = await request({
  accountSid, authToken, path: "Messages.json",
  params: { To: inputs.to, PageSize: 50 }
});
const { messages } = (await fetch(req.url, req)).json;

Number lookup

Lookup lives on its own host, so pass an absolute path:

const req = await request({
  accountSid, authToken,
  host: "lookups.twilio.com",
  path: `/v2/PhoneNumbers/${encodeURIComponent(inputs.phone)}`,
  params: { Fields: "line_type_intelligence" }
});

Gotchas

• request is async. A host call is a round trip.
• Parameter names are PascalCase. To, From, Body, MediaUrl — Twilio ignores what it does not recognize, so a lowercase body sends an empty message rather than an error.
• Numbers are E.164. [phone], country code and all.
• Only *.twilio.com hosts are accepted, so a mistyped host fails here rather than mailing credentials somewhere else.
• An error is a non-2xx with JSON. Read res.json.message and res.json.code; the code maps to Twilio's error reference.