Meta Advanced APIs & Future Capabilities Roadmap

This specification documents advanced WhatsApp Cloud API endpoints evaluated for future phases of SMSPort. These endpoints provide low-level delivery event reconciliation and native Meta WhatsApp bot configuration.

1. Message History & Delivery Audit API

Endpoint: GET https://graph.facebook.com/{Version}/{Message-History-ID}/events
Authentication: Authorization: Bearer <System_User_Token>
Status: Roadmap (Future Phase)
Current SMSPort Alternative: Real-time webhooks at /api/v1/whatsapp/webhook capture all message status changes (sent, delivered, read, failed) with zero polling overhead.

Overview & Purpose

While SMSPort relies on webhooks for sub-second delivery tracking, webhook delivery can occasionally fail due to transient network drops, receiver downtime, or proxy restarts.

This endpoint serves as Meta's authoritative audit trail for a specific message, allowing the platform to inspect every timestamped state transition from acceptance to read receipt.

Request Parameters

Path Parameters

Parameter	Type	Required	Description
`Version`	`string`	Yes	Graph API version (e.g. `v23.0`).
`Message-History-ID`	`string`	Yes	Unique WhatsApp Business Message History ID associated with the sent message.

Query Parameters

Parameter	Type	Required	Default	Description
`delivery_status`	`string`	No	All	Filter events by status: `ACCEPTED`, `SENT`, `DELIVERED`, `READ`, `ERROR`.
`fields`	`string`	No	Default	Comma-separated field list: `cursor`, `node{id,delivery_status,occurrence_timestamp,status_timestamp,error_description,application,webhook_update_state,webhook_uri}`.
`limit`	`integer`	No	`25`	Maximum number of events per page (1–100).
`after`	`string`	No	None	Pagination cursor for next page (`paging.cursors.after`).
`before`	`string`	No	None	Pagination cursor for previous page (`paging.cursors.before`).

Response Schema & Event Lifecycle

{
  "data": [
    {
      "cursor": "QVFIUkl...",
      "node": {
        "id": "event_1001",
        "delivery_status": "DELIVERED",
        "occurrence_timestamp": 1742034120,
        "status_timestamp": 1742034122,
        "application": {
          "id": "1234567890",
          "name": "SMSPort Production"
        },
        "webhook_update_state": "SUCCESS",
        "webhook_uri": "https://app.smsport.com/api/v1/whatsapp/webhook"
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUkl...",
      "after": "QVFIUkl..."
    }
  }
}

Event Status Hierarchy

ACCEPTED: Meta Cloud API servers accepted the outbound request from SMSPort.
SENT: Meta dispatched the payload to WhatsApp's global carrier gateway.
DELIVERED: The message arrived on the recipient's device (double gray checkmarks).
READ: The recipient opened the conversation (double blue checkmarks).
ERROR: Delivery failed. The error_description field contains the failure reason.

Future SMSPort Implementation Plan

Delivery Dispute Resolution Modal: Allow operators in Live Chat to click "Audit Delivery Trail" on any message to fetch Meta's raw audit timestamps.
Reconciliation Worker: A periodic background job (e.g. every 30 minutes) to reconcile stuck sent messages that never received a delivered webhook callback.

2. WhatsApp Business Bot Configuration API

Endpoint: GET https://graph.facebook.com/{Version}/{WABA-Bot-ID}
Authentication: Authorization: Bearer <System_User_Token>
Status: Roadmap (Future Phase)
Current SMSPort Alternative: Visual Bot Builder and AI Agent runtime manage conversational state, NLP intents, buttons, and routing directly inside the SMSPort engine.

Overview & Purpose

Meta supports native in-chat interactive features directly rendered within the WhatsApp mobile keyboard:

Slash Commands (commands): A command menu that opens when a customer types / in WhatsApp (e.g. /order, /track, /agent).
Conversation Prompts (prompts): Icebreaker bubbles shown to first-time chatters.
Welcome Messages (enable_welcome_message): Automatic greetings triggered natively before any server roundtrip.

Request Parameters

Path Parameters

Parameter	Type	Required	Description
`Version`	`string`	Yes	Graph API version (e.g. `v23.0`).
`WABA-Bot-ID`	`string`	Yes	Unique Meta Bot ID associated with the WhatsApp Business Account.

Query Parameters

Parameter	Type	Required	Description
`fields`	`string`	No	Comma-separated list: `id`, `prompts`, `commands`, `enable_welcome_message`.

Response Schema

{
  "id": "bot_987654321",
  "enable_welcome_message": true,
  "prompts": [
    "Check order status",
    "Book an appointment",
    "Speak with an agent"
  ],
  "commands": [
    {
      "command_name": "track",
      "command_description": "Track your active shipment"
    },
    {
      "command_name": "support",
      "command_description": "Connect with human support"
    },
    {
      "command_name": "menu",
      "command_description": "Browse our service catalog"
    }
  ]
}

Future SMSPort Implementation Plan

Visual Bot Builder Native Sync: In the Bot Builder Settings panel, add a "Publish Native Slash Commands" toggle.
When toggled, SMSPort will sync the bot's root trigger nodes directly to Meta's commands array, providing WhatsApp users with instant keyboard autocomplete.