> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Messaging

> Send WhatsApp messages from your function with ctx.jelou: text, images, buttons, lists, carousels, HSM templates, and more.

## What is `ctx.jelou`?

`ctx.jelou` is the built-in messaging client. It lets you send WhatsApp messages directly from your function. Available automatically when the company has Jelou API credentials configured.

## Check availability

```typescript theme={null}
if (!ctx.jelou.available) {
  return { error: "Messaging not configured for this company" };
}
```

## Send messages

### `ctx.jelou.send(options)`

Returns `{ messageId: string }`.

<Tabs>
  <Tab title="Text">
    ```typescript theme={null}
    await ctx.jelou.send({
      type: "text",
      to: "+593987654321",
      text: "Your order #1234 is on its way",
    });
    ```
  </Tab>

  <Tab title="Image">
    ```typescript theme={null}
    await ctx.jelou.send({
      type: "image",
      to: "+593987654321",
      mediaUrl: "https://cdn.example.com/product.jpg",
      caption: "Product: Dell XPS 15 Laptop",
    });
    ```
  </Tab>

  <Tab title="Buttons">
    ```typescript theme={null}
    await ctx.jelou.send({
      type: "buttons",
      to: "+593987654321",
      text: "How would you like to receive your order?",
      buttons: [
        { id: "delivery", title: "Home delivery" },
        { id: "pickup", title: "Store pickup" },
        { id: "express", title: "Express shipping" },
      ],
    });
    ```
  </Tab>

  <Tab title="List">
    ```typescript theme={null}
    await ctx.jelou.send({
      type: "list",
      to: "+593987654321",
      text: "Select a product category:",
      buttonText: "View categories",
      sections: [
        {
          title: "Electronics",
          rows: [
            { id: "laptops", title: "Laptops", description: "Notebooks and portables" },
            { id: "phones", title: "Phones", description: "Smartphones and accessories" },
          ],
        },
      ],
    });
    ```
  </Tab>

  <Tab title="Carousel">
    ```typescript theme={null}
    await ctx.jelou.send({
      type: "carousel",
      to: "+593987654321",
      cards: [
        {
          mediaUrl: "https://cdn.example.com/laptop.jpg",
          body: "Dell XPS 15 — $1,299",
          buttons: [
            { id: "buy_laptop", title: "Buy" },
            { id: "info_laptop", title: "More info" },
          ],
        },
      ],
    });
    ```
  </Tab>

  <Tab title="Location">
    ```typescript theme={null}
    await ctx.jelou.send({
      type: "location",
      to: "+593987654321",
      lat: -2.1894,
      lng: -79.8891,
      name: "Store Guayaquil",
      address: "Av. 9 de Octubre 123",
    });
    ```
  </Tab>
</Tabs>

Other supported types: `video`, `audio`, `file`, `sticker`, `contacts`, `quick_reply`, `cta_url`, `flow`.

## Send HSM templates

### `ctx.jelou.sendTemplate(options)`

Returns `Array<{ id, destination }>`.

```typescript theme={null}
await ctx.jelou.sendTemplate({
  template: "order_confirmation",
  to: "+593987654321",
  language: "es",
  params: ["Maria", "ORD-1234", "$59.99"],
});

// Multiple recipients
await ctx.jelou.sendTemplate({
  template: "monthly_promo",
  to: ["+593987654321", "+593912345678"],
  params: ["20%", "April 30"],
});
```

## Bot override

All messages default to `ctx.bot.id`. Override with `botId`:

```typescript theme={null}
await ctx.jelou.send({
  type: "text",
  to: "+593987654321",
  text: "Message from another bot",
  botId: "bot-notifications-456",
});
```

## Error handling

```typescript theme={null}
import { JelouApiError } from "@jelou/functions";

try {
  await ctx.jelou.send({ type: "text", to: "+593987654321", text: "Hello" });
} catch (err) {
  if (err instanceof JelouApiError) {
    if (err.isRateLimit()) return { error: "rate_limit" };
    if (err.isAuth()) return { error: "auth_error" };
    if (err.isValidation()) return { error: "validation_error" };
  }
  throw err;
}
```

## Testing

```typescript theme={null}
import { createMockContext, createMockJelouClient } from "@jelou/functions/testing";

const mockJelou = createMockJelouClient();
const ctx = createMockContext({ jelou: mockJelou });

await ctx.jelou.send({ type: "text", to: "+593987654321", text: "Test" });
mockJelou.calls.length; // 1
mockJelou.reset();
```