> ## 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.

***

## 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.

### 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.

### 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

> **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.

> **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.

> **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.

> **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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.