Magic Links

What are Magic Links?

Magic Links let you create shareable URLs that capture verified WhatsApp phone numbers and collect structured data through conversational flows. When someone taps a magic link, it opens a WhatsApp conversation with your Neuron bot, which captures their phone number, runs an optional Q&A flow to collect additional data, and delivers the results via webhook, REST API, or JS SDK callback.

Use Cases

Common use cases include phone verification (verify a user's WhatsApp number with a single tap), registration (collect name, email, and other details via WhatsApp conversation), lead capture (QR code on a flyer links to a magic link that collects interest and phone number), authentication (app generates a single-use link, user taps it, app receives verified phone), and data collection (surveys, RSVPs, or preferences collected conversationally).

Creating a Magic Link

Create a magic link from your bot's Magic Links tab:

1. 1

   Name and slug

   Give the link a name and URL-friendly slug. The slug becomes part of the shareable URL (e.g., /m/signup-link).

2. 2

   Choose type

   Single-use links expire after one person completes the flow — ideal for authentication. Multi-use links can be used by many people — ideal for registration and lead capture.

3. 3

   Choose flow

   Direct opens WhatsApp immediately. Landing Page shows a branded page first with a "Continue with WhatsApp" button. Adaptive auto-detects the best option.

4. 4

   Add fields (optional)

   Define fields to collect (name, email, phone, number, or select). The bot asks each question in order and validates responses before moving to the next.

Flow Types

Direct flow: The link is a wa.me URL that opens WhatsApp with a pre-filled message containing a unique session code. Best for mobile-first audiences. Landing Page flow: The link opens a branded web page with your heading, description, and a "Continue with WhatsApp" button. A session is created when the page loads, and the button opens WhatsApp. Best when you want to set context before the WhatsApp conversation. Adaptive flow: Neuron picks the best option based on the user's device and context.

Fields & Q&A

When a magic link has fields, the bot enters a scripted Q&A mode. It asks each field question in order, validates the response (e.g., email format, numeric values, select options), and re-asks on validation failure. Once all fields are collected, the session resolves. If "Use bot for conversation" is enabled, the bot hands off to its full AI after the scripted fields are complete.

Sessions

Each magic link interaction creates a session. Sessions track the unique code sent via WhatsApp, the user's phone number, collected field data, and resolution status. Single-use sessions expire after 15 minutes by default; multi-use sessions expire after 24 hours. View all sessions from the magic link detail page.

JavaScript SDK

The JS SDK provides a Paystack-style inline integration for capturing verified WhatsApp numbers on any website — no backend required. Include the script, call setup() with your public API key and link slug, and handle the onSuccess callback.

<script src="https://neuron-api.letschop.io/sdk/magic-link.js"></script>
<script>
const handler = NeuronMagicLink.setup({
  key: 'nrn_pub_your_api_key',
  link: 'signup-link',
  referrerData: { userId: '42' },
  onSuccess: (result) => {
    console.log(result.phone);       // Verified WhatsApp number
    console.log(result.collectedData); // Field responses
    console.log(result.contactId);    // Neuron contact ID
  },
  onError: (error) => console.error(error),
});

// Open the flow (creates session, opens WhatsApp, polls for completion)
handler.open();
</script>

REST API

For server-side integration, use the Bot API endpoints. Create sessions with POST /api/v1/bot-api/magic-links/:id/sessions (returns a session ID, code, and wa.me URL). Poll session status with GET /api/v1/bot-api/magic-links/:id/sessions/:sessionId. Session creation requires a public or secret API key.

# Create a session
curl -X POST https://neuron-api.letschop.io/api/v1/bot-api/magic-links/signup-link/sessions \
  -H "Authorization: Bearer nrn_pub_your_key" \
  -H "Content-Type: application/json" \
  -d '{"referrerData": {"userId": "42"}}'

# Poll for completion
curl https://neuron-api.letschop.io/api/v1/bot-api/magic-links/signup-link/sessions/SESSION_ID \
  -H "Authorization: Bearer nrn_pub_your_key"

Webhook Events

Magic links fire four webhook events through the existing outbound webhook system: magic_link.session_created (flow initiated), magic_link.resolved (phone captured and all fields collected), magic_link.expired (session timed out), and magic_link.field_collected (individual field answered). Configure outbound webhooks on your bot to receive these events.

Contact Integration

When a magic link session resolves, Neuron automatically creates or links a contact by phone number. Collected fields like name and email update the contact record. A tag "magic:<slug>" is added for segmentation. The contact is then available for broadcasts, campaigns, and future bot interactions.

Landing Page Configuration

For landing page flow links, customize the page with a heading, description, button text, and terms text. The landing page is mobile-first, shows a branded "Continue with WhatsApp" button, and includes real-time status updates via SSE (Server-Sent Events) while waiting for the user to complete the WhatsApp flow.

Analytics

Each magic link's detail page shows analytics: total sessions, completed sessions, completion rate, and a breakdown by status (pending, in progress, completed, expired, failed). Use these metrics to optimize your flows — high drop-off may indicate too many fields or unclear instructions.