AgentSMS

Interface

Read and send SMS messages from the device

Access SMS methods through agent.sms. Allows reading and sending SMS messages on the device. Requires SMS permissions to be granted.

AgentSMS Interface

TypeScript

interface AgentSMS {
  readSMS(options?: ReadSMSOptions): Promise<SmsMessage[]>;
  sendSMS(phoneNumber: string, message: string): Promise<boolean>;
}

interface ReadSMSOptions {
  phoneNumber?: string;        // Filter by phone number (partial match)
  limit?: number;              // Max messages (default: 20)
  skip?: number;               // Pagination offset (default: 0)
  sortOrder?: "asc" | "desc";  // Sort by date (default: "desc")
  type?: number;               // 1=inbox, 2=sent, 3=draft
  minDate?: number;            // After this timestamp (ms)
  maxDate?: number;            // Before this timestamp (ms)
}

Methods

`readSMS()`

TypeScript

readSMS(options?: ReadSMSOptions): Promise<SmsMessage[]>

Reads SMS messages from the device. Useful for automations that need to read verification codes or other SMS content. All options are optional - calling with no arguments returns the 20 most recent messages.Since 2.138 (150)

Parameters

Name	Type	Description
`options?`	`ReadSMSOptions`	Optional filtering and pagination options

Returns

Promise<SmsMessage[]>Array of SMS messages

Examples

Read latest SMS messages

TypeScript

const messages = await agent.sms.readSMS();

for (const msg of messages) {
  console.log("From:", msg.address);
  console.log("Body:", msg.body);
  console.log("Date:", new Date(msg.date).toLocaleString());
  console.log("---");
}

Find OTP/verification code

TypeScript

// Get recent inbox messages from the last 5 minutes
const fiveMinAgo = Date.now() - 5 * 60 * 1000;
const messages = await agent.sms.readSMS({
  type: 1,       // inbox only
  minDate: fiveMinAgo,
  limit: 10,
});

// Find message with OTP code
const otpMsg = messages.find(m =>
  m.body.includes("code") || m.body.includes("OTP")
);

if (otpMsg) {
  const codeMatch = otpMsg.body.match(/\b\d{4,6}\b/);
  if (codeMatch) {
    console.log("OTP code:", codeMatch[0]);
  }
}

Filter by phone number

TypeScript

const messages = await agent.sms.readSMS({
  phoneNumber: "+1234567890",
  limit: 5,
});

console.log("Messages from +1234567890:", messages.length);

Paginate through messages

TypeScript

// First page
const page1 = await agent.sms.readSMS({ limit: 10, skip: 0 });

// Second page
const page2 = await agent.sms.readSMS({ limit: 10, skip: 10 });

Read sent messages (oldest first)

TypeScript

const sentMessages = await agent.sms.readSMS({
  type: 2,            // sent messages
  sortOrder: "asc",   // oldest first
  limit: 20,
});

`sendSMS()`

TypeScript

sendSMS(phoneNumber: string, message: string): Promise<boolean>

Sends an SMS message from the device. Long messages are automatically split into multiple parts. Requires SEND_SMS permission.Since 2.138 (150)

Parameters

Name	Type	Description
`phoneNumber`	`string`	Recipient phone number
`message`	`string`	Text message to send

Returns

Promise<boolean>Resolves to true if the message was sent successfully

Examples

Send a simple SMS

TypeScript

const success = await agent.sms.sendSMS("+1234567890", "Hello from automation!");
console.log("SMS sent:", success);

Send SMS with error handling

TypeScript

try {
  await agent.sms.sendSMS("+1234567890", "Your verification code is 1234");
  console.log("SMS sent successfully");
} catch (error) {
  console.error("Failed to send SMS:", error.message);
}

Send SMS using job variables

TypeScript

const { phoneNumber, messageTemplate } = agent.arguments.jobVariables;
await agent.sms.sendSMS(phoneNumber, messageTemplate);

Types

ReadSMSOptions

Options for filtering and paginating SMS messages.

TypeScript

interface ReadSMSOptions {
  phoneNumber?: string;        // Filter by phone number (partial match)
  limit?: number;              // Max messages to return (default: 20)
  skip?: number;               // Messages to skip (default: 0)
  sortOrder?: "asc" | "desc";  // Sort by date (default: "desc")
  type?: number;               // SMS type: 1=inbox, 2=sent, 3=draft
  minDate?: number;            // Only after this timestamp (Unix ms)
  maxDate?: number;            // Only before this timestamp (Unix ms)
}

ReadSMSOptions Properties

Property	Type	Description
`phoneNumber?`	`string`	Filter messages by phone number. Uses partial matching so both full and partial numbers work.
`limit?`	`number`	Maximum number of messages to return. Defaults to 20.
`skip?`	`number`	Number of messages to skip for pagination. Defaults to 0.
`sortOrder?`	`"asc" \| "desc"`	Sort order by date. "desc" returns newest first (default), "asc" returns oldest first.
`type?`	`number`	Filter by SMS type: 1 = inbox (received), 2 = sent, 3 = draft. Omit to include all types.
`minDate?`	`number`	Only return messages after this timestamp (Unix milliseconds).
`maxDate?`	`number`	Only return messages before this timestamp (Unix milliseconds).

SmsMessage

Represents an SMS message.

TypeScript

interface SmsMessage {
  id: string;       // Unique message ID
  address: string;  // Phone number
  body: string;     // Message text content
  date: number;     // Timestamp (Unix ms)
  type: number;     // 1=inbox, 2=sent, 3=draft
  read: boolean;    // Has been read
  seen: boolean;    // Has been seen
}

SmsMessage Properties

Property	Type	Description
`id`	`string`	Unique identifier for the SMS message
`address`	`string`	Phone number - sender for inbox messages, recipient for sent messages
`body`	`string`	The text content of the message
`date`	`number`	Message timestamp in Unix milliseconds
`type`	`number`	Message type: 1 = inbox (received), 2 = sent, 3 = draft
`read`	`boolean`	Whether the message has been read
`seen`	`boolean`	Whether the message has been seen by the user

Permissions Note

SMS operations require the READ_SMS and SEND_SMS permissions to be granted on the device. The app will request these permissions automatically during setup. If permissions are denied, the corresponding methods will return an error.