Mensagens

O que é `ctx.jelou`?

ctx.jelou é o cliente de mensagens integrado. Permite enviar mensagens de WhatsApp diretamente da sua função. Disponível automaticamente quando a empresa tem credenciais da API do Jelou configuradas.

Verificar disponibilidade

if (!ctx.jelou.available) {
  return { error: "Mensagens não configuradas para esta empresa" };
}

Enviar mensagens

`ctx.jelou.send(options)`

Retorna { messageId: string }.

Texto
Imagem
Botões
Lista
Carrossel

await ctx.jelou.send({
  type: "text",
  to: "+5511987654321",
  text: "Seu pedido #1234 está a caminho",
});

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

await ctx.jelou.send({
  type: "buttons",
  to: "+5511987654321",
  text: "Como deseja receber seu pedido?",
  buttons: [
    { id: "delivery", title: "Entrega em casa" },
    { id: "pickup", title: "Retirada na loja" },
    { id: "express", title: "Entrega express" },
  ],
});

await ctx.jelou.send({
  type: "list",
  to: "+5511987654321",
  text: "Selecione uma categoria:",
  buttonText: "Ver categorias",
  sections: [
    {
      title: "Eletrônicos",
      rows: [
        { id: "laptops", title: "Laptops" },
        { id: "phones", title: "Celulares" },
      ],
    },
  ],
});

await ctx.jelou.send({
  type: "carousel",
  to: "+5511987654321",
  cards: [
    {
      mediaUrl: "https://cdn.example.com/laptop.jpg",
      body: "Dell XPS 15 — R$6.999",
      buttons: [{ id: "buy", title: "Comprar" }],
    },
  ],
});

Outros tipos suportados: video, audio, file, sticker, contacts, quick_reply, cta_url, location, flow.

Templates HSM

await ctx.jelou.sendTemplate({
  template: "confirmacao_pedido",
  to: "+5511987654321",
  language: "pt_BR",
  params: ["Maria", "PED-1234", "R$59,99"],
});

Validar templates antes de enviar

Um sendTemplate falha em silêncio por três motivos: o nome está errado, o idioma não está aprovado, ou você manda mais ou menos parâmetros do que o template espera. ctx.templateRegistry dá acesso ao catálogo de templates aprovados do canal para detectar isso antes de chamar a Meta.

handler: async (input, ctx) => {
  if (!ctx.templateRegistry.available) {
    return await ctx.jelou.send({ type: "text", to: input.telefone, text: "Seu pedido está pronto" });
  }

  if (await ctx.templateRegistry.has("confirmacao_pedido", "pt_BR")) {
    await ctx.templateRegistry.validate({
      name: "confirmacao_pedido",
      language: "pt_BR",
      params: [input.nome, input.pedidoId],
    });

    await ctx.jelou.sendTemplate({
      template: "confirmacao_pedido",
      to: input.telefone,
      language: "pt_BR",
      params: [input.nome, input.pedidoId],
    });
  }

  return { enviado: true };
}

Métodos

Método	Descrição
`templateRegistry.available`	`false` se a empresa não tem credenciais configuradas
`templateRegistry.has(nome, idioma?)`	`true` se o canal atual tem o template. Nunca lança erro
`templateRegistry.hasAnywhere(nome)`	`true` se qualquer canal da empresa tem. Para auditorias, não para decidir um envio
`templateRegistry.get(nome, idioma)`	Retorna o template ou `null`. Lança erro se não há canal associado
`templateRegistry.list()`	Todos os templates aprovados do canal atual
`templateRegistry.validate({ name, language, params })`	Lança erro se o nome, o idioma, o estado ou a quantidade de parâmetros não corresponderem
`templateRegistry.for(botId)`	Retorna um catálogo vinculado a outro canal

has() e hasAnywhere() são verificações booleanas: se não há canal associado ou o catálogo não responde, registram um aviso e retornam false em vez de lançar erro. Quando você precisa de uma resposta definitiva use get(), list() ou validate(), que lançam TemplateRegistryError com um code: unknown_template, language_not_approved, param_count_mismatch, template_paused, registry_unavailable ou no_bot_context.

sendTemplate não valida por conta própria — o catálogo é somente leitura. Chame validate() explicitamente quando quiser a verificação.

Em cron e execuções diferidas

Em um disparo de cron ou de uma execução diferida não há canal resolvido, então has() sempre retornaria false. Leve o botId no seu próprio payload e vincule o catálogo explicitamente:

handler: async (input, ctx) => {
  // O botId viajou no payload que você agendou antes
  const registro = ctx.templateRegistry.for(input.botId);

  if (await registro.has("lembrete_consulta", "pt_BR")) {
    await ctx.jelou.sendTemplate({
      template: "lembrete_consulta",
      to: input.telefone,
      language: "pt_BR",
      params: [input.data],
      botId: input.botId,
    });
  }
}

for(botId) é seguro em qualquer rota: em uma requisição normal simplesmente revincula ao canal indicado.

Os resultados ficam em cache por 90 segundos. Um template aprovado agora mesmo pode não aparecer até o cache expirar.

Tratamento de erros

import { JelouApiError } from "@jelou/functions";

try {
  await ctx.jelou.send({ type: "text", to: "+5511987654321", text: "Olá" });
} catch (err) {
  if (err instanceof JelouApiError) {
    if (err.isRateLimit()) return { error: "rate_limit" };
    if (err.isAuth()) return { error: "auth_error" };
  }
  throw err;
}

Testes

import { createMockContext, createMockJelouClient } from "@jelou/functions/testing";

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

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

Primeiros Passos

Desenvolvedor

Jelou CLI

Mensagens Outbound

Gestão

Marketplace

Canais

Configuração

Faturamento

O que é `ctx.jelou`?

Verificar disponibilidade

Enviar mensagens

`ctx.jelou.send(options)`

Templates HSM

Validar templates antes de enviar

Métodos

Em cron e execuções diferidas

Tratamento de erros

Testes

​O que é ctx.jelou?

​Verificar disponibilidade

​Enviar mensagens

​ctx.jelou.send(options)

​Templates HSM

​Validar templates antes de enviar

​Métodos

​Em cron e execuções diferidas

​Tratamento de erros

​Testes

O que é `ctx.jelou`?

Verificar disponibilidade

Enviar mensagens

`ctx.jelou.send(options)`

Templates HSM

Validar templates antes de enviar

Métodos

Em cron e execuções diferidas

Tratamento de erros

Testes