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

# Architecture

> How a Vodafone Bulk Text integration fits into your systems.

A typical Vodafone Bulk Text integration connects your business system to the authentication service, campaign API, Vodafone messaging gateway, and callback endpoints.

```mermaid title="Integration architecture" theme={"system"}
flowchart LR
  CRM["Customer system or CRM"] --> Auth["Authentication service"]
  Auth --> Token["JWT access token"]
  Token --> API["Vodafone Bulk Text API"]
  CRM --> API
  API --> Gateway["Vodafone messaging gateway"]
  Gateway --> Network["Recipient mobile network"]
  Network --> Handset["Recipient handset"]
  Gateway --> Processing["Processing webhook"]
  Network --> DLR["Delivery receipt"]
  Handset --> Inbound["Inbound SMS relay"]
  Processing --> CRM
  DLR --> CRM
  Inbound --> CRM
```

## Main components

| Component                            | Role                                                                         |
| ------------------------------------ | ---------------------------------------------------------------------------- |
| Customer system or CRM               | Stores recipients, message templates, campaign records, and callback status. |
| Authentication service               | Issues short-lived JWT access tokens from `https://auth.vodafone.com/token`. |
| Vodafone Bulk Text API               | Accepts campaign requests and sender list requests.                          |
| Vodafone messaging gateway           | Processes messages and submits SMS traffic for delivery.                     |
| Recipient mobile network and handset | Receives the SMS and returns delivery status where available.                |
| Callback endpoint                    | Receives processing webhooks, DLRs, and inbound message relays.              |

## Recommended flow

<Steps>
  <Step title="Prepare recipients">
    Validate mobile numbers, consent status, Sender ID, and `notifyId` values in your own system before sending.
  </Step>

  <Step title="Authenticate">
    Request an access token. Store credentials securely and keep tokens out of browser code, logs, and analytics tools.
  </Step>

  <Step title="Send the campaign">
    Call `POST /api/v2/Campaign` with the message text, Sender ID, recipients, and optional schedule.
  </Step>

  <Step title="Receive callbacks">
    Accept processing webhooks and delivery receipts with `200 OK` after your system records the payload.
  </Step>

  <Step title="Reconcile status">
    Match callbacks to your records with `notifyId` and update campaign, customer, or reporting tables.
  </Step>
</Steps>

## Operational expectations

* Build callback handlers to be idempotent.
* Respond with `200 OK` only after you have accepted the payload.
* Store raw callback payloads when auditability matters.
* Treat missing or delayed DLRs as unconfirmed until your own timeout policy expires.
* Use [Troubleshooting](/guides/troubleshooting) for common integration issues.