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

# OTP Link

> Secure verification through WhatsApp with clickable links

## Overview

The OTP Link feature provides a secure verification method by sending clickable links via WhatsApp. Unlike traditional OTP codes, this approach allows users to verify their identity with a single tap, creating a smoother user experience while maintaining security.

## How It Works

1. Your application requests an OTP link to be sent to a user's WhatsApp
2. CrunchzApp generates a unique verification link and delivers it via WhatsApp
3. The user clicks the link, which opens in their browser
4. Upon successful verification, the user is redirected to your application or a callback URL is triggered

## Available Methods

### Basic Link Request

Send a standard verification link to a WhatsApp contact.

<Tabs>
  <Tab title="Basic Usage">
    ```php theme={null}
    use CrunchzApp\CrunchzApp;

    CrunchzApp::otp('link')
      ->contact('xxx@c.us')
      ->send();
    ```
  </Tab>

  <Tab title="Parameters">
    | Parameter | Type   | Required | Description                                                         |
    | --------- | ------ | -------- | ------------------------------------------------------------------- |
    | contact   | string | Yes      | The WhatsApp contact ID in the format '[xxx@c.us](mailto:xxx@c.us)' |
  </Tab>
</Tabs>

<Note>
  By default, OTP links expire after 15 minutes and use a standard verification message.
</Note>

### Custom Link Request

Create a fully customized verification experience with custom prompts, messages, and callbacks.

<Tabs>
  <Tab title="Advanced Usage">
    ```php theme={null}
    use CrunchzApp\CrunchzApp;
    use Illuminate\Support\Str;

    $code = strtoupper(Str::random(6));
    return CrunchzApp::otp('link')
      ->contact('xxx@c.us')
      ->prompt('Give me login code at MyRepublic')
      ->responseMessage(
        successResponse: 'This is your code, please make it safe and secure *##'.$code.'##*',
        failedResponse: 'Your phone number or your prompt are incorrect',
        expiredResponse: 'This link is expired, please try a new link',
      )
      ->callback(
        successCallback: 'https://github.com/crunchzApp/success-callback',
        failedCallback: 'https://github.com/crunchzApp/failed-callback'
      )
      ->send();
    ```
  </Tab>

  <Tab title="Parameters">
    | Parameter       | Type   | Required | Description                                                         |
    | --------------- | ------ | -------- | ------------------------------------------------------------------- |
    | contact         | string | Yes      | The WhatsApp contact ID in the format '[xxx@c.us](mailto:xxx@c.us)' |
    | prompt          | string | No       | Custom text prompt shown to the user                                |
    | successResponse | string | No       | Custom message shown after successful verification                  |
    | failedResponse  | string | No       | Custom message shown after failed verification                      |
    | expiredResponse | string | No       | Custom message shown when link has expired                          |
    | successCallback | string | No       | URL to call when verification succeeds                              |
    | failedCallback  | string | No       | URL to call when verification fails                                 |
  </Tab>
</Tabs>

<Warning>
  When using custom codes in your response messages, ensure they are properly formatted and highlighted (as shown with the *##code##* syntax in the example).
</Warning>

## Customization Options

<AccordionGroup>
  <Accordion title="Custom Prompts">
    The `prompt()` method allows you to customize the text shown to users when they click the verification link. This can be used to provide context about why they're being asked to verify.
  </Accordion>

  <Accordion title="Custom Response Messages">
    The `responseMessage()` method lets you define custom messages for different verification outcomes:

    * `successResponse`: Shown after successful verification
    * `failedResponse`: Shown after failed verification
    * `expiredResponse`: Shown when the link has expired
  </Accordion>

  <Accordion title="Callback URLs">
    The `callback()` method allows you to specify webhook URLs that will be called when verification succeeds or fails:

    * `successCallback`: Called on successful verification
    * `failedCallback`: Called on failed verification
  </Accordion>
</AccordionGroup>

## Common Use Cases

<AccordionGroup>
  <Accordion title="Passwordless Login">
    Send a verification link to users instead of requiring them to remember and enter passwords.
  </Accordion>

  <Accordion title="Account Recovery">
    Provide a secure way for users to regain access to their accounts without complex recovery processes.
  </Accordion>

  <Accordion title="Secure Actions Confirmation">
    Verify user intent for sensitive operations like payments or account changes with a simple click.
  </Accordion>

  <Accordion title="Two-Factor Authentication">
    Add an extra layer of security by requiring link verification in addition to password login.
  </Accordion>
</AccordionGroup>

## Error Handling

<Tabs>
  <Tab title="Invalid Link">
    ```json theme={null}
    {
      "success": false,
      "message": "Invalid verification link",
      "error_code": "LINK_INVALID"
    }
    ```
  </Tab>

  <Tab title="Expired Link">
    ```json theme={null}
    {
      "success": false,
      "message": "Verification link has expired",
      "error_code": "LINK_EXPIRED"
    }
    ```
  </Tab>

  <Tab title="Already Used">
    ```json theme={null}
    {
      "success": false,
      "message": "Verification link already used",
      "error_code": "LINK_USED"
    }
    ```
  </Tab>
</Tabs>