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

# Twilio Messaging

> Send SMS and WhatsApp payment confirmations to customers automatically

## Overview

The HitPay Twilio integration automatically sends SMS and WhatsApp messages to your customers after a successful payment. This helps you keep customers informed and build trust with instant payment confirmations.

### Key Features

* **SMS notifications** — Send customizable text messages after every successful charge
* **WhatsApp messages** — Send WhatsApp messages using Twilio Content Templates
* **Customizable templates** — Personalize messages with customer name, amount, currency, and more
* **Multi-channel** — Enable SMS and WhatsApp independently
* **Automatic triggering** — Messages are sent automatically after each successful payment

***

## Prerequisites

Before connecting, make sure you have:

1. An active **HitPay** account
2. An active **Twilio** account ([sign up here](https://www.twilio.com/try-twilio))
3. Your Twilio **Account SID** and **Auth Token** (found on your [Twilio Console](https://console.twilio.com/))
4. At least one **phone number** purchased in Twilio with SMS capability
5. *(For WhatsApp)* A pre-approved **Content Template** created in Twilio's Content Template Builder

***

## Connecting Twilio

1. In your HitPay dashboard, go to **Integrations**.

2. On the **Available** tab, find the **Twilio** card and click it.

3. Enter your Twilio credentials:

   | Field           | Description                              | Example                              |
   | --------------- | ---------------------------------------- | ------------------------------------ |
   | **Account SID** | Your Twilio Account SID                  | `AC1234567890abcdef1234567890abcdef` |
   | **Auth Token**  | Your Twilio Auth Token                   | Found in Twilio Console              |
   | **From Number** | Your Twilio phone number in E.164 format | `+6591234567`                        |

4. Click **Connect**. HitPay will validate your credentials and verify that the phone number exists on your Twilio account with SMS capability.

<Note>Your Auth Token is stored securely and is never displayed after the initial connection.</Note>

***

## Configuring Messaging

After connecting, configure your messaging settings on the Twilio integration page.

### Enable Messaging

Toggle **Enable messaging** to start sending messages after successful payments. When disabled, no messages will be sent even if the connection is active.

### Choose Channels

Select which channels to use for sending messages:

* **SMS** — Standard text messages
* **WhatsApp** — Messages sent via WhatsApp (requires a Content Template)

You can enable one or both channels.

### Customize Your SMS Template

Write a custom message template using the following placeholders:

| Placeholder       | Replaced With            | Example       |
| ----------------- | ------------------------ | ------------- |
| `{customer_name}` | Customer's name          | John Doe      |
| `{amount}`        | Formatted payment amount | 50.00         |
| `{currency}`      | Currency code            | SGD           |
| `{reference}`     | Charge reference ID      | ch\_abc123... |
| `{business_name}` | Your business name       | My Cat Shop   |

**Example template:**

```
Hi {customer_name}, your payment of {currency} {amount} to {business_name} has been received. Reference: {reference}. Thank you!
```

<Note>SMS templates have a maximum length of 1,600 characters.</Note>

### Configure WhatsApp *(optional)*

If you enable the WhatsApp channel:

1. Create a **Content Template** in your [Twilio Console](https://console.twilio.com/) using the Content Template Builder.
2. Your template can include up to 5 variables that map to:
   * `{{1}}` — Customer name
   * `{{2}}` — Amount
   * `{{3}}` — Currency
   * `{{4}}` — Reference
   * `{{5}}` — Business name
3. Once your template is approved by Twilio, copy the **Content SID** and enter it in the WhatsApp Content SID field in HitPay.

<Warning>WhatsApp messages require a Content Template SID. Messages will fail if no template is configured.</Warning>

### Save Settings

Click **Save** to apply your messaging configuration. Messages will be sent automatically for all future successful charges.

***

## How It Works

1. A customer completes a payment on any of your HitPay sales channels
2. HitPay detects the successful charge and checks for active messaging integrations
3. If the customer provided a phone number, HitPay formats it and sends the configured message(s)
4. SMS and WhatsApp messages are sent asynchronously so they don't delay the payment flow

### Retry Logic

If a message fails to send (e.g., temporary network issue), HitPay will retry up to **3 times** with increasing delays (30s, 60s, 120s). If all retries fail due to an authentication error, the connection will be marked as **Failed** and you will need to reconnect.

***

## Disconnecting Twilio

1. On the Twilio integration page, click **Disconnect**.
2. A confirmation dialog will appear. Click **Disconnect** to confirm.

After disconnecting, no further messages will be sent. You can reconnect at any time with your Twilio credentials.

***

## Important Notes

* **Messages are only sent for successful charges.** Failed or pending payments do not trigger messages.
* **Customer phone number required.** Messages are only sent when the customer provides a phone number during checkout.
* **Phone numbers are automatically formatted** to E.164 international format before sending.
* **One Twilio connection per business.** Each HitPay business account requires its own Twilio connection.
* **Connection failures trigger alerts.** If your Twilio credentials expire or become invalid, HitPay will mark the connection as failed and stop sending messages until you reconnect.

***

## FAQs

<AccordionGroup>
  <Accordion title="How is this different from the email notifications HitPay sends?">
    HitPay includes a free built-in email notification service that automatically sends payment confirmation emails to your customers. The Twilio integration is for businesses that want to go further — sending custom **SMS** or **WhatsApp** messages using your own Twilio account. This gives you full control over the message content, branding, and delivery channel.
  </Accordion>

  <Accordion title="My customers are not receiving messages. What should I check?">
    Start by checking your **Twilio logs** first — go to your [Twilio Console](https://console.twilio.com/) > Monitor > Logs to see if the message was sent and its delivery status. If the message was sent but not delivered, the issue is on the carrier or recipient side.

    If no message appears in your Twilio logs, check the following in HitPay:

    1. **Messaging is enabled** — Verify the messaging toggle is turned on.
    2. **Connection status** — Check that the connection status is "Linked", not "Failed".
    3. **Customer phone number** — Ensure the customer provided a valid phone number during checkout.
    4. **Twilio balance** — Check your Twilio account has sufficient balance for sending messages.
    5. **Phone number capability** — Verify your Twilio phone number has SMS enabled in the Twilio Console.
  </Accordion>

  <Accordion title="Why are my WhatsApp messages failing?">
    1. **Content Template SID** — Verify the Content SID is correctly entered and the template is approved in Twilio.
    2. **Template variables** — Ensure your Content Template uses the correct variable format (`{{1}}` through `{{5}}`).
    3. **WhatsApp opt-in** — Customers may need to have interacted with your WhatsApp number before receiving messages.
  </Accordion>

  <Accordion title="My connection is marked as Failed">
    This typically means your Twilio credentials have become invalid. Go to the Twilio integration page and click **Reconnect** with valid Account SID and Auth Token.
  </Accordion>
</AccordionGroup>