Agent Skills

Ready-made patterns for wiring Sendexa into AI agents. Copy a skill into your agent's tool definitions and it's ready to use.

What is a Skill?

A skill is a tool definition — a JSON schema that describes a callable action for an AI agent. The agent reads the schema to understand what the tool does, then calls your backend which executes the Sendexa API request. The examples below show both the tool schema and the handler code.

Two-Factor Authentication

A two-tool skill that lets an agent send an OTP and then verify the PIN the user provides. Useful for identity verification flows inside a conversational interface.

JSON

[
  {
    "name": "send_otp",
    "description": "Send a one-time password to the user's phone number. Returns an otpId to use for verification.",
    "input_schema": {
      "type": "object",
      "properties": {
        "phone":      { "type": "string", "description": "E.164 or local phone number." },
        "brand_name": { "type": "string", "description": "Sender name shown on the SMS." }
      },
      "required": ["phone", "brand_name"]
    }
  },
  {
    "name": "verify_otp",
    "description": "Verify the PIN the user entered against an open OTP session.",
    "input_schema": {
      "type": "object",
      "properties": {
        "otp_id": { "type": "string", "description": "The otpId returned by send_otp." },
        "pin":    { "type": "string", "description": "The 4-8 digit PIN the user entered." }
      },
      "required": ["otp_id", "pin"]
    }
  }
]

Smart Notification Dispatcher

Let the agent choose between SMS, WhatsApp, and email depending on what contact info is available. One tool schema, three channels.

JSON

{
  "name": "send_notification",
  "description": "Send a notification to a user via the best available channel (email, WhatsApp, or SMS). Provide at least one of email, phone, or whatsapp_number.",
  "input_schema": {
    "type": "object",
    "properties": {
      "message":          { "type": "string",  "description": "The notification text." },
      "email":            { "type": "string",  "description": "Recipient email address." },
      "phone":            { "type": "string",  "description": "Phone number for SMS." },
      "whatsapp_number":  { "type": "string",  "description": "WhatsApp-enabled phone number." },
      "subject":          { "type": "string",  "description": "Email subject line (email only)." },
      "sender":           { "type": "string",  "description": "Sender name or address." }
    },
    "required": ["message", "sender"]
  }
}

Voice Alert Call

Make an outbound TTS call for urgent notifications — password resets, fraud alerts, or emergency broadcasts.

JSON

{
  "name": "make_voice_alert",
  "description": "Call a phone number and read a message aloud using text-to-speech. Use for urgent alerts that require immediate attention.",
  "input_schema": {
    "type": "object",
    "properties": {
      "to":       { "type": "string", "description": "The phone number to call." },
      "from":     { "type": "string", "description": "Caller ID / sender name." },
      "message":  { "type": "string", "description": "The text to read aloud." },
      "language": { "type": "string", "description": "BCP-47 language code, e.g. en-US.", "default": "en-US" },
      "repeat":   { "type": "integer","description": "How many times to repeat the message.", "default": 2 }
    },
    "required": ["to", "from", "message"]
  }
}

WhatsApp Interactive Flow

Send a WhatsApp message with reply buttons and let the agent branch based on the user's choice — confirmations, surveys, menu navigation.

tools/whatsapp-buttons.ts

import { Sendexa } from "sendexa";

const client = new Sendexa({
  apiKey:    process.env.SENDEXA_API_KEY!,
  apiSecret: process.env.SENDEXA_API_SECRET!,
});

// Tool: send_whatsapp_buttons
export async function send_whatsapp_buttons(args: {
  to: string;
  body_text: string;
  buttons: Array<{ id: string; title: string }>;
}) {
  await client.whatsapp.sendInteractive(args.to, {
    type: "button",
    body: { text: args.body_text },
    action: {
      buttons: args.buttons.map((b) => ({
        type:  "reply",
        reply: { id: b.id, title: b.title },
      })),
    },
  });
  return { sent: true };
}

// Usage example:
// await send_whatsapp_buttons({
//   to: "+233244123456",
//   body_text: "Confirm your appointment for tomorrow at 10:00 AM?",
//   buttons: [
//     { id: "confirm", title: "Confirm" },
//     { id: "reschedule", title: "Reschedule" },
//     { id: "cancel",    title: "Cancel" },
//   ],
// });