Connect WhatsApp

• A Meta Business account and a WhatsApp Business Account with a phone number, following Meta’s Cloud API getting-started guide. Meta’s free test number is enough for development.
• For the CLI path: the phone number ID, the WABA ID, and an access token from WhatsApp → API Setup in your Meta app. For production, generate a permanent token through a system user.
• An agent with a promoted production version; see Release an agent.

lua channels

lua channels list

​

Channel behavior

lua webhooks subscribe --webhook-name delivery-tracker --event message.delivered
lua webhooks subscribe --webhook-name delivery-tracker --event message.failed

​

Users who hide their phone number

import { PreProcessor, Channels } from 'lua-cli';

const ALLOWED = new Set(['15551234567', '15557654321']);

export default new PreProcessor({
  name: 'phone-gate',
  description: 'Let registered phone numbers through and ask users who hide their number to share it',
  priority: 10,
  async execute(user, _messages, channel) {
    const numbers = user._luaProfile.mobileNumbers.map((n) => n.replace(/\D/g, ''));
    if (numbers.some((n) => ALLOWED.has(n))) return { action: 'proceed' };

    if (channel === 'whatsapp' && numbers.length === 0) {
      try {
        await Channels.whatsapp.requestPhoneNumber({
          to: { userId: user._luaProfile.userId },
          text: 'To use this service, please share your phone number so we can check you are registered.',
        });
        return { action: 'block' };
      } catch {
        return { action: 'block', response: 'Please share your phone number with us to use this service.' };
      }
    }

    return { action: 'block', response: 'Sorry, this number is not registered.' };
  },
});

​

Disconnect a number

• If Meta refuses the release, the channel stays connected and the dashboard shows Meta’s reason.
• Meta allows 10 release attempts per number in 72 hours.
• A number that also runs in the WhatsApp Business app can’t be released from Lua. Disconnect it in the app under Settings → Account → Business Platform.
• Deleting your Lua organization releases its WhatsApp numbers.

​

Limits

• Free-form sends: 24 hours after the end user’s last inbound message. Message templates have no window but need Meta’s approval.
• Closed-window queueing to a +1 (US or Canada) number: Meta blocks the marketing-category opt-in prompt, so the send still returns queued: true with a warning and the prompt may never arrive. Send an approved WhatsApp message template to those recipients instead.
• Reactions: the target message must be at most 30 days old.
• A number connects to one agent at a time. Linking it again, to this or another agent, is refused with Channel already exists.
• Meta’s messaging tiers and quality rating govern volume. The rating appears in the channel’s detail view in lua channels and in the admin dashboard.

​

Troubleshooting

​

Next steps