# Event & Payload Reference

**What are Communication Apps?**
Communication Apps react to events triggered by Salla. Each event delivers a specific context object to your App Function, and your function is expected to return a structured response.

For App Functions fundamentals (execution types, `Resp` utility, runtime constraints, testing), see the [App Functions reference](https://docs.salla.dev/1726817m0).

---

## Available events

The events your function receives are controlled by the **Supported Features** you declared in the Partner Portal.

| Event | Fires when | Controlled by Supported Feature |
|---|---|---|
| `communication.sms.send` | Salla needs to send an SMS to a customer | Local SMS and/or International SMS |
| `communication.email.send` | Salla needs to send an email to a customer | Email |
| `communication.whatsapp.send` | Salla needs to send a WhatsApp message to a customer | WhatsApp |

---

## Payload Schema (`CommunicationEvent`)

<Tabs>
    <Tab title="TypeScript Interface">
        This is the full TypeScript shape of the context object your handler receives.

        ```typescript
        interface CommunicationData {
          /** One or more recipients. Phone numbers for SMS/WhatsApp, email addresses for Email. */
          notifiable: string[];

          /** Why this message is being sent (see Event types table). */
          type: string;

          /** Ready-to-send message body. May be Arabic or English. */
          content: string;

          /** The Salla store entity this message relates to. null for OTPs and broadcasts. */
          entity: {
            id:   number | string;
            type: "order" | "cart" | "shipment" | "product" | "feedback" | "repurchase_reminder" | string;
          } | null;

          /** Extra context: { customer_id: number } or OTP { code: string } */
          meta: Record<string, any>;
        }

        interface CommunicationPayload {
          event:      "communication.sms.send" | "communication.email.send" | "communication.whatsapp.send";
          merchant:   number;
          created_at: string;
          data:        CommunicationData;
        }

        interface CommunicationEvent {
          merchant: { id: string };
          payload:  CommunicationPayload;
          settings: Record<string, string>;
        }
        ```
    </Tab>
    <Tab title="JSON Example">
        ```json
        {
          "payload": {
            "event": "communication.sms.send",
            "merchant": 292111819,
            "created_at": "Mon Nov 10 2025 17:18:13 GMT+0300",
            "data": {
              "notifiable": ["+96656000000"],
              "type": "order.status.updated",
              "content": "Your order #123 is now [Delivered]",
              "entity": { "id": 12345, "type": "order" },
              "meta": { "customer_id": 98765 }
            }
          },
          "settings": {
            "sms_api_key": "your-key",
            "sms_sender_id": "MyStore"
          },
          "merchant": { "id": "292111819" }
        }
        ```
    </Tab>
</Tabs>

---

## Event Reference

These are the common event types your app receives through the `data.type` field.

:::note[Feature Requirement]
Ensure the relevant features (**"Email"**, **"Local SMS"**, or **"WhatsApp"**) are enabled in the [**Partners Portal**](https://portal.salla.partners) for these events to trigger correctly.
:::



<Tabs>
    <Tab title="Orders">
        <Accordion title="Order Status Confirmation" icon="material-two-tone-confirmation_number">
            Sent when an order is created and is pending payment.
            - **Type**: `order.status.confirmation`
            - **Supported Channels**: Email, SMS, WhatsApp
            - **Entity Type**: `order`
            - **Meta Fields**: `customer_id` (number)
            ```json
            {
              "event": "communication.email.send",
              "data": {
                "notifiable": ["customer@example.com"],
                "type": "order.status.confirmation",
                "content": "We received your order #123. Please complete payment.",
                "entity": { "id": 123, "type": "order" },
                "meta": { "customer_id": 987 }
              }
            }
            ```
        </Accordion>

        <Accordion title="Order Status Updated" icon="material-two-tone-update" defaultOpen={false}>
            Sent when the status of an order is changed.
            - **Type**: `order.status.updated`
            - **Supported Channels**: Email, SMS, WhatsApp
            - **Entity Type**: `order`
            - **Meta Fields**: `customer_id` (number)
            ```json
            {
              "event": "communication.sms.send",
              "data": {
                "notifiable": ["+96656000000"],
                "type": "order.status.updated",
                "content": "Your order #123 is now [Delivered]",
                "entity": { "id": 123, "type": "order" },
                "meta": { "customer_id": 987 }
              }
            }
            ```
        </Accordion>

        <Accordion title="Invoice Issued" icon="material-two-tone-receipt" defaultOpen={false}>
            Sent when an invoice is generated for an order.
            - **Type**: `order.invoice.issued`
            - **Supported Channels**: Email, SMS, WhatsApp
            - **Entity Type**: `order`
            - **Meta Fields**: `customer_id` (number)
            ```json
            {
              "event": "communication.email.send",
              "data": {
                "notifiable": ["customer@example.com"],
                "type": "order.invoice.issued",
                "content": "Your invoice for order #123 is ready.",
                "entity": { "id": 123, "type": "order" },
                "meta": { "customer_id": 987 }
              }
            }
            ```
        </Accordion>

        <Accordion title="Digital Product Code" icon="material-two-tone-qr_code" defaultOpen={false}>
            Sent when a customer purchases a digital product that includes a code.
            - **Type**: `product.digital.code`
            - **Supported Channels**: Email, SMS, WhatsApp
            - **Entity Type**: `order`
            - **Meta Fields**: `customer_id` (number)
            ```json
            {
              "event": "communication.sms.send",
              "data": {
                "notifiable": ["+96656000000"],
                "type": "product.digital.code",
                "content": "Your digital code for Order #123 is: ABC-DEF",
                "entity": { "id": 123, "type": "order" },
                "meta": { "customer_id": 987 }
              }
            }
            ```
        </Accordion>

        <Accordion title="Order Refunded" icon="material-two-tone-assignment_return" defaultOpen={false}>
            Sent when an order is refunded to the customer.
            - **Type**: `order.refund.processed`
            - **Supported Channels**: SMS, WhatsApp
            - **Entity Type**: `order`
            - **Meta Fields**: `customer_id` (number)
            ```json
            {
              "event": "communication.email.send",
              "data": {
                "notifiable": ["customer@example.com"],
                "type": "order.refund.processed",
                "content": "A refund has been processed for your order #123.",
                "entity": { "id": 123, "type": "order" },
                "meta": { "customer_id": 987 }
              }
            }
            ```
        </Accordion>

        <Accordion title="Create New Order" icon="material-two-tone-card_giftcard" defaultOpen={false}>
            Sent when a new order has been created.
            - **Type**: `order.notification.create`
            - **Supported Channels**: WhatsApp
            - **Entity Type**: `order`
            - **Meta Fields**: `customer_id` (number)
            ```json
            {
              "event": "communication.whatsapp.send",
              "data": {
                "notifiable": ["+96656000000"],
                "type": "order.notification.create",
                "content": "Your order #12332 has been recieved.",
                "entity": { "id": 123, "type": "order" },
                "meta": { "customer_id": 987 }
              }
            }
            ```
        </Accordion>
        <Accordion title="Gift Order Placed" icon="material-two-tone-card_giftcard" defaultOpen={false}>
            Sent when a customer places an order as a gift.
            - **Type**: `order.gift.placed`
            - **Supported Channels**: SMS, WhatsApp
            - **Entity Type**: `order`
            - **Meta Fields**: `customer_id` (number)
            ```json
            {
              "event": "communication.sms.send",
              "data": {
                "notifiable": ["+96656000000"],
                "type": "order.gift.placed",
                "content": "Someone sent you a gift!",
                "entity": { "id": 123, "type": "order" },
                "meta": { "customer_id": 987 }
              }
            }
            ```
        </Accordion>

        <Accordion title="Payment Reminder" icon="material-two-tone-notification_important" defaultOpen={false}>
            Sent as a reminder for a pending payment.
            - **Type**: `payment.reminder.due`
            - **Supported Channels**: SMS, WhatsApp
            - **Entity Type**: `order`
            - **Meta Fields**: `customer_id` (number)
            ```json
            {
              "event": "communication.sms.send",
              "data": {
                "notifiable": ["+96656000000"],
                "type": "payment.reminder.due",
                "content": "Friendly reminder: Order #123 is waiting for payment.",
                "entity": { "id": 123, "type": "order" },
                "meta": { "customer_id": 987 }
              }
            }
            ```
        </Accordion>
    </Tab>

    <Tab title="Customers & Products">
        <Accordion title="Abandoned Cart" icon="material-two-tone-shopping_cart">
            - **Type**: `customer.cart.abandoned`
            - **Supported Channels**: SMS, WhatsApp
            - **Entity Type**: `cart`
            - **Meta Fields**: `customer_id` (number), `discount` (Percentage / Fixed), `expires_at`

            ```json
            {
              "event": "communication.whatsapp.send",
              "data": {
                "notifiable": ["+96656000000"],
                "type": "customer.cart.abandoned",
                "content": "You left items in your cart!",
                "entity": { "id": 789, "type": "cart" },
                  "meta": { "customer_id": 987, "discount": "10%", "expires_at: "2024-10-01 00:00:00" }
              }
            }
            ```
        </Accordion>

        <Accordion title="Product Availability Alert" icon="material-two-tone-event_available" defaultOpen={false}>
            - **Type**: `product.availability.alert`
            - **Supported Channels**: Email, SMS, WhatsApp
            - **Entity Type**: `product`
            - **Meta Fields**: `customer_id` (number)
            ```json
            {
              "event": "communication.sms.send",
              "data": {
                "notifiable": ["+96656000000"],
                "type": "product.availability.alert",
                "content": "The product you wanted is back in stock.",
                "entity": { "id": 555, "type": "product" },
                "meta": { "customer_id": 987 }
              }
            }
            ```
        </Accordion>

        <Accordion title="Rating Request" icon="material-two-tone-star" defaultOpen={false}>
            - **Type**: `customer.rating.request`
            - **Supported Channels**: Email, SMS, WhatsApp
            - **Entity Type**: `order`
            ```json
            {
              "event": "communication.whatsapp.send",
              "data": {
                "notifiable": ["+96656000000"],
                "type": "customer.rating.request",
                "content": "How was your order #123?",
                "entity": { "id": 123, "type": "order" },
                "meta": { "customer_id": 987 }
              }
            }
            ```
        </Accordion>

        <Accordion title="Feedback Reply" icon="material-two-tone-forum" defaultOpen={false}>
            - **Type**: `customer.feedback.reply`
            - **Supported Channels**: Email, SMS, WhatsApp
            - **Entity Type**: `feedback`
            ```json
            {
              "event": "communication.email.send",
              "data": {
                "notifiable": ["customer@example.com"],
                "type": "customer.feedback.reply",
                "content": "The merchant replied to your review.",
                "entity": { "id": 321, "type": "feedback" },
                "meta": { "customer_id": 987 }
              }
            }
            ```
        </Accordion>

        <Accordion title="Repurchase Reminder" icon="material-two-tone-replay" defaultOpen={false}>
      Sent when a repurchase reminder is triggered, encouraging the customer to buy a previously purchased product again.
      - **Type**: `customer.repurchase.reminder`
      - **Supported Channels**: Email, SMS, WhatsApp
      - **Entity Type**: `repurchase_reminder`
      - **Meta Fields**: `customer_id`, `discount`, `expires_at`

      ```json
      {
        "event": "communication.whatsapp.send",
        "data": {
          "notifiable": ["+96656000000"],
          "type": "customer.repurchase.reminder",
          "content": "حان وقت إعادة طلب المنتج. اطلب الآن من الرابط: https://store.example/redirect/reorder-reminder/xxx",
          "entity": { "id": 84213097, "type": "repurchase_reminder" },
          "locale": "ar",
          "meta": { 
            "customer_id": 698792337,
            "discount": "10%",
            "expires_at": "2026-07-20 12:00:00"
          }
        }
      }
      ```
      </Accordion>
        <Accordion title="Loyalty Points Earned" icon="material-two-tone-loyalty" defaultOpen={false}>
            - **Type**: `customer.loyalty.earned`
            - **Supported Channels**: Email, SMS, WhatsApp
            - **Entity Type**: `null`
            - **Meta Fields**: `customer_id`, `points`
            ```json
            {
              "event": "communication.sms.send",
              "data": {
                "notifiable": ["+96656000000"],
                "type": "customer.loyalty.earned",
                "content": "You earned 50 loyalty points.",
                "entity": null,
                "meta": { "customer_id": 987, "points": 50 }
              }
            }
            ```
        </Accordion>
    </Tab>

    <Tab title="Auth & System">
        <Accordion title="OTP Verification" icon="material-two-tone-vibration">
            - **Type**: `auth.otp.verification`
            - **Supported Channels**: Email, SMS, WhatsApp
            - **Entity Type**: `null`
            - **Meta Fields**: `code` (string)
            ```json
            {
              "event": "communication.sms.send",
              "data": {
                "notifiable": ["+96656000000"],
                "type": "auth.otp.verification",
                "content": "Your verification code is: 1234",
                "entity": null,
                "meta": { "code": "1234" }
              }
            }
            ```
        </Accordion>

        <Accordion title="Marketing Campaign" icon="material-two-tone-campaign" defaultOpen={false}>
            - **Type**: `marketing.campaign.broadcast`
            - **Supported Channels**: Email, SMS, WhatsApp
            - **Entity Type**: `null`
            ```json
            {
              "event": "communication.sms.send",
              "data": {
                "notifiable": ["+96656000000"],
                "type": "marketing.campaign.broadcast",
                "content": "Flash Sale! Get 50% off.",
                "entity": null,
                "meta": {}
              }
            }
            ```
        </Accordion>

        <Accordion title="System Messages/Alerts" icon="material-two-tone-report_problem" defaultOpen={false}>
            - **Types**: `system.message.custom`, `system.alert.general`
            - **Supported Channels**: Email, SMS, WhatsApp
            - **Entity Type**: `null`
            - **Meta Fields**: `customer_id`
            ```json
            {
              "event": "communication.email.send",
              "data": {
                "notifiable": ["customer@example.com"],
                "type": "system.message.custom",
                "content": "This is a custom message from the store.",
                "entity": null,
                "meta": { "customer_id": 987 }
              }
            }
            ```
        </Accordion>
    </Tab>
</Tabs>

---

## Entity Type Reference

Use these references to learn how to fetch more details via the Salla API.

| Entity Type | Description | API Reference |
|---|---|---|
| `order` | A unique identifier for a store order. | [Order API](https://docs.salla.dev/api-5394146) |
| `shipment` | A unique identifier for a shipment. | [Shipment API](https://docs.salla.dev/api-5394232) |
| `cart` | A unique identifier for a shopping cart. | [Abandoned Cart API](https://docs.salla.dev/api-5394138) |
| `feedback` | A unique identifier for a customer review. | [Review API](https://docs.salla.dev/16603963e0) |
| `product` | A unique identifier for a product. | [Product API](https://docs.salla.dev/api-5394200) |
| `repurchase_reminder` | A merchant-configured repurchase reminder. | — (no public fetch endpoint; use the pre-composed `content`) |