> For the complete documentation index, see [llms.txt](https://docs.oomus.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.oomus.org/integrations/messaging.md).

# Messaging (WhatsApp & SMS)

Oomus CampaignID integrates two complementary messaging channels for distributing digital health cards: **WhatsApp** (Meta Graph API v25.0) and **SMS** (Orange SMS API OAuth2).

***

## WhatsApp

### Technology

Oomus CampaignID uses the **Meta Graph API version 25.0** (WhatsApp Business Platform) for sending WhatsApp messages. This is Meta's official API for large-scale business-to-consumer communications.

### Prerequisites

To configure the WhatsApp integration, you need:

| Prerequisites            | Description                                           | Where to get it                                        |
| ------------------------ | ----------------------------------------------------- | ------------------------------------------------------ |
| Meta Business Account    | Verified Business Manager account                     | [business.facebook.com](https://business.facebook.com) |
| Meta App                 | App in your Business Manager                          | Meta Developer Portal                                  |
| WhatsApp Business Number | Dedicated number for WhatsApp Business (not personal) | Number provider or local operator                      |
| Permanent access token   | Meta System User Access Token                         | Meta Developer > System Users                          |
| Phone Number ID          | WhatsApp number ID in Meta                            | Meta WhatsApp Manager                                  |

> Your WhatsApp Business number cannot be used on the personal WhatsApp app at the same time.

### Meta Business account verification

Meta requires Business account verification before allowing high-volume sending:

1. Go to **Meta Business Manager > Settings > Business Verification**
2. Submit your organization’s documents (articles of incorporation, official documents)
3. Verification time: 1–5 business days
4. Once verified, your sending limit increases from 250 to 1,000 then 100,000+ conversations/day

### Configuration in Oomus CampaignID

1. In the Oomus interface, navigate to **Settings > Integrations > WhatsApp**
2. Enter:
   * **Meta access token** : your System User Access Token
   * **Phone Number ID** : your WhatsApp number ID
   * **Sender number** : your WhatsApp Business number (E.164 format)
3. Click **"Test send"** to send a test message

### WhatsApp message format

Each WhatsApp message sent by Oomus includes:

* **Image** : beneficiary card PNG (high resolution)
* **Text** : personalized message with dynamic variables

Dynamic variables available in the message:

| Variable             | Value                   |
| -------------------- | ----------------------- |
| `{first_name}`       | Beneficiary first name  |
| `{last_name}`        | Last name               |
| `{card_code}`        | Unique card code        |
| `{programme_name}`   | Program name            |
| `{issue_date}`       | Issue date              |
| `{verification_url}` | Verification portal URL |

**Example message:**

```
Hello {first_name} {last_name},

Here is your {programme_name} card. Please keep this message safe.

Card code: {card_code}
Verification: {verification_url}
```

### Meta compliance and message templates

For messages initiated by your program (outside the 24-hour session), Meta requires the use of **Message Templates** pre-approved.

* Recommended category: **Utility** (transactional notifications)
* Required language(s): French, English (depending on your markets)
* Approval time: 24–72 hours

The Oomus team provides pre-written message templates for common health use cases (vaccination, nutrition, health insurance).

***

## SMS

### Technology

Oomus CampaignID uses the**Orange SMS API** with authentication **OAuth2** for sending SMS in West Africa.

### Orange geographic coverage

| Country       | Code | Operator          |
| ------------- | ---- | ----------------- |
| Senegal       | SN   | Orange Senegal    |
| Côte d'Ivoire | CI   | Orange CI         |
| Mali          | ML   | Orange Mali       |
| Burkina Faso  | BF   | Orange BF         |
| Guinea        | GN   | Orange Guinea     |
| Cameroon      | CM   | Orange Cameroon   |
| Madagascar    | MG   | Orange Madagascar |
| Tunisia       | TN   | Orange Tunisia    |
| Egypt         | EG   | Orange Egypt      |

> For countries outside Orange coverage, contact the Oomus team to discuss integration with a local partner operator.

### SMS prerequisites

| Prerequisites             | Description                                                     |
| ------------------------- | --------------------------------------------------------------- |
| Orange developer account  | Account on [developer.orange.com](https://developer.orange.com) |
| Application created       | Application with access to "SMS" in the Orange developer portal |
| Client ID + Client Secret | OAuth2 credentials for your application                         |
| Sender Name               | Alphanumeric sender name (max 11 characters, e.g.: `SANTE-SN`)  |

### Configuration in Oomus CampaignID

1. In the Oomus interface, navigate to **Settings > Integrations > SMS**
2. Enter:
   * **Client ID** : your Orange API client ID
   * **Client Secret** : your Orange API client secret
   * **Sender Name** : sender name (e.g.: `SANTE-SN`, `VACC-CI`)
   * **Default country** : country code for numbers without a country prefix
3. Click **"Test send"** to send a test SMS

### SMS message format

SMS are limited to **160 characters** (standard SMS). Beyond that, the message is split into concatenated SMS messages (charged per segment).

**Example distribution SMS:**

```
[PNV-SN] Hello Aminata, your vaccination card
is ready. Download it: https://v.oomus.health/c/DKR-VAC-9XQ7LM2A
```

***

## Sending from the DHIS2 interface

The most common way to send cards is from the **Distribution** tab in the DHIS2 view:

### Individual sending

1. Select an enrollment in the DHIS2 view
2. Click the **"Distribution"**
3. The phone number is automatically extracted from the mapped DHIS2 attribute
4. Choose the channel: WhatsApp or SMS
5. Edit the message if needed
6. Click **"Send"**

### Bulk sending

1. From the DHIS2 enrollment list, select multiple beneficiaries
2. Click **"Bulk distribution"**
3. Choose the channel
4. Confirm sending

***

## Logging and tracking

Each sent message is logged with:

| Information              | Description                                          |
| ------------------------ | ---------------------------------------------------- |
| Timestamp                | Send date and time (UTC)                             |
| Channel                  | WhatsApp or SMS                                      |
| Status                   | `pending` / `sent` / `delivered` / `read` / `failed` |
| Message ID               | External ID (Meta Message ID or Orange Message ID)   |
| Recipient number         | Partially masked (e.g.: `+22177***4567`)             |
| Campaign / enrollment ID | Internal reference (no PII)                          |

Logs can be viewed in:

* **Dashboard > Distribution > Logs**
* **Campaign > Distribution tab > History**

***

## Best practices

### WhatsApp

* Obtain **explicit consent** from beneficiaries before sending WhatsApp messages (GDPR / local regulations)
* Use Meta-approved templates for sends outside the 24-hour session
* Send the cards within 24 hours of generation for the best experience

### SMS

* Make sure phone numbers in DHIS2 are in **E.164** (`+221771234567`)
* Avoid sending between 9 p.m. and 7 a.m. (local time) to comply with local regulations
* For large campaigns (>10,000 SMS), schedule sends outside peak hours

***

## Next steps

* [Multichannel distribution](/features/distribution.md) — Distribution overview
* [DHIS2 guide](/integrations/dhis2.md) — Distribution from DHIS2
* [Google Wallet](/integrations/google-wallet.md) — Google Wallet channel


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.oomus.org/integrations/messaging.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.