Messaging

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

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

Send messages

`ctx.jelou.send(options)`

Returns { messageId: string }.

await ctx.jelou.send({
  type: "text",
  to: "+593987654321",
  text: "Your order #1234 is on its way",
});

await ctx.jelou.send({
  type: "image",
  to: "+593987654321",
  mediaUrl: "https://cdn.example.com/product.jpg",
  caption: "Product: Dell XPS 15 Laptop",
});

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" },
  ],
});

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" },
      ],
    },
  ],
});

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" },
      ],
    },
  ],
});

await ctx.jelou.send({
  type: "location",
  to: "+593987654321",
  lat: -2.1894,
  lng: -79.8891,
  name: "Store Guayaquil",
  address: "Av. 9 de Octubre 123",
});

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

Send HSM templates

`ctx.jelou.sendTemplate(options)`

Returns Array<{ id, destination }>.

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"],
});

Validate templates before sending

A sendTemplate fails silently for three reasons: the name is misspelled, the language is not approved, or you pass more or fewer params than the template expects. ctx.templateRegistry gives you the channel’s approved-template catalog so you can catch that before calling Meta.

handler: async (input, ctx) => {
  if (!ctx.templateRegistry.available) {
    return await ctx.jelou.send({ type: "text", to: input.phone, text: "Your order is ready" });
  }

  if (await ctx.templateRegistry.has("order_confirmation", "es")) {
    await ctx.templateRegistry.validate({
      name: "order_confirmation",
      language: "es",
      params: [input.name, input.orderId],
    });

    await ctx.jelou.sendTemplate({
      template: "order_confirmation",
      to: input.phone,
      language: "es",
      params: [input.name, input.orderId],
    });
  }

  return { sent: true };
}

Methods

Method	Description
`templateRegistry.available`	`false` if the company has no credentials configured
`templateRegistry.has(name, language?)`	`true` if the current channel has the template. Never throws
`templateRegistry.hasAnywhere(name)`	`true` if any channel in the company has it. For audits, not for deciding a send
`templateRegistry.get(name, language)`	Returns the template or `null`. Throws if no channel is bound
`templateRegistry.list()`	Every approved template for the current channel
`templateRegistry.validate({ name, language, params })`	Throws if the name, language, state or param count do not match
`templateRegistry.for(botId)`	Returns a catalog bound to another channel

has() and hasAnywhere() are boolean checks: if no channel is bound or the catalog does not respond, they log a warning and return false instead of throwing. When you need a definitive answer use get(), list() or validate(), which throw TemplateRegistryError with a code: unknown_template, language_not_approved, param_count_mismatch, template_paused, registry_unavailable or no_bot_context.

sendTemplate does not validate on its own — the catalog is read-only. Call validate() explicitly when you want the check.

In cron and deferred runs

On a cron or deferred run fire there is no channel resolved, so has() would always return false. Carry the botId in your own payload and bind the catalog explicitly:

handler: async (input, ctx) => {
  // The botId travelled in the payload you booked earlier
  const registry = ctx.templateRegistry.for(input.botId);

  if (await registry.has("appointment_reminder", "es")) {
    await ctx.jelou.sendTemplate({
      template: "appointment_reminder",
      to: input.phone,
      language: "es",
      params: [input.date],
      botId: input.botId,
    });
  }
}

for(botId) is safe on any path: on a normal request it simply re-binds to the given channel.

Results are cached for 90 seconds. A template approved moments ago may not appear until the cache expires.

Channel override

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

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

Error handling

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

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();

Getting Started

Developer

Jelou CLI

Outbound Messaging

Management

Marketplace

Channels

Configuration

Billing

What is `ctx.jelou`?

Check availability

Send messages

`ctx.jelou.send(options)`

Send HSM templates

`ctx.jelou.sendTemplate(options)`

Validate templates before sending

Methods

In cron and deferred runs

Channel override

Error handling

Testing

​What is ctx.jelou?

​Check availability

​Send messages

​ctx.jelou.send(options)

​Send HSM templates

​ctx.jelou.sendTemplate(options)

​Validate templates before sending

​Methods

​In cron and deferred runs

​Channel override

​Error handling

​Testing

What is `ctx.jelou`?

Check availability

Send messages

`ctx.jelou.send(options)`

Send HSM templates

`ctx.jelou.sendTemplate(options)`

Validate templates before sending

Methods

In cron and deferred runs

Channel override

Error handling

Testing