# Get Started
In this guide, you will learn how to build a working Communication App that seamlessly integrates with Salla. By leveraging App Functions, you can intercept Salla's native notification events and route SMS, Email, or WhatsApp messages through your own preferred third-party communication provider.
## Prerequisites
Before diving into the integration, ensure you have completed the foundational setup for your app.
If you do not already have a partner account, [sign up here](https://portal.salla.partners/).
[Create a new app](https://salla.dev/blog/salla-communication-apps/) and select **Communication App** as the app type.
[Install your app](https://salla.dev/blog/how-to-test-your-app-using-salla-demo-stores/) on a demo store to test with real data and configure your [App Settings](https://salla.dev/blog/how-to-build-app-settings-form/).
## System Architecture
The following diagram illustrates how Salla intercepts notification events and routes them through your custom App Function to your preferred communication provider.
```mermaid
sequenceDiagram
participant Store as 🛒 Store
participant Salla as 🖥 Salla Platform
participant App as <> Your App
participant Provider as ✈ Provider API
Store->>Salla: 1. Event occurs (order, OTP, cart, review, account)
Salla->>App: 2. Fire communication event (SMS, Email, or WhatsApp)
App->>Provider: 3. Send message via provider (Twilio, SendGrid, etc.)
alt ✓ delivery successful
Provider-->>App: 4.1 Message delivered
App-->>Salla: 4.2 Return success response
Salla-->>Store: 4.3 Communication complete
else ✗ delivery failed
Provider-->>App: 5.1 Delivery error
App-->>Salla: 5.2 Return error response
Salla-->>Store: 5.3 Communication failed
end
```
## Implementation Guide
Follow these steps to configure your app, write the delivery logic, and publish your custom communication handler.
Supported Features declare which communication channels your app handles. When a merchant installs your app, it becomes the active handler for every message type you declare—Salla routes all matching messages through your App Function instead of the default provider.
:::warning[Action Required]
Your app cannot go live until at least one feature is selected.
:::
1. In the Partner Portal, open your app and scroll down to the **Supported Feature** section. Click the **Supported Feature** button to open the feature selector.
2. Choose a channel tab and tick the features your app will handle:
| Tab | Feature | What your app handles |
|---|---|---|
| SMS | **Local SMS** | All SMS messages to KSA numbers |
| SMS | **International SMS** | All SMS messages to numbers outside KSA |
| Email | **Email** | All email messages |
| Whatsapp | **Whatsapp** | All WhatsApp messages |
3. Click **Save**.
:::note[Handling Multiple Channels]
You can select multiple features. For example, tick both **Local SMS** and **International SMS** if your provider handles both domestic and international delivery. Each feature you select means your app takes full ownership of that message type.
:::
In the Partner Portal app editor, scroll to **App Functions** and click **Add New Function**.
The function builder consists of four main sections:
* **Function Name:** A descriptive identifier (e.g., `sms-delivery-handler`).
* **Action Selector:** The specific event that triggers this function.
* **Code Editor:** Where you write the custom handler logic.
* **Preview Panel:** A testing environment using real demo store data.
**Select the Event Action:**
Click **Select Action** and choose the channel you want to handle.
| Select this action | To handle |
|---|---|
| `communication.sms.send` | Outgoing SMS messages |
| `communication.email.send` | Outgoing email messages |
| `communication.whatsapp.send` | Outgoing WhatsApp messages |
:::info[]
You can create one function per channel, or a single master function that branches based on `payload.event`.)
:::
Once you select an action, the editor pre-populates the function signature. Replace the body with your delivery logic.
Below is a minimal SMS handler that sends a message via a provider using credentials stored in your app settings.
```typescript
export default async (context: CommunicationEvent): Promise => {
const { payload, settings } = context;
const { notifiable, content } = payload.data;
try {
const response = await fetch("[https://api.your-provider.com/send](https://api.your-provider.com/send)", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
api_key: settings.sms_api_key,
to: notifiable[0],
message: content,
}),
});
if (response.ok) {
return Resp.success().setMessage("SMS sent successfully.");
}
return Resp.error().setMessage("Failed to send SMS.");
} catch (err) {
return Resp.error().setMessage("An error occurred during delivery.");
}
};
```
:::info[More Examples]
Full implementation examples for SMS, Email, and WhatsApp channels can be found on the [Examples](https://docs.salla.dev/doc-2006120) page.
:::
Before publishing, you must test and validate your function with real store data using the preview panel.
1. In the function editor, click **Select Store** in the preview panel and choose your demo store.
2. Enter a test value in the preview parameters (for communication events, this is usually a message or customer ID). Then, click **Save and Preview**.
The preview panel will display the execution status, the response data returned by your function, execution time, `console.log()` outputs, and detailed error traces if the function failed.
:::warning[Check Your Settings]
Verify that your settings values are populated. If `context.settings` is empty, it means you have not yet filled in the App Settings form on your demo store.
:::
Once the function works in the preview environment, test the complete end-to-end flow from the merchant's perspective.
1. Log in to your demo store's dashboard via the Partner Portal (click **Dashboard** on your demo store list).
2. Navigate to **Apps** -> **Settings** -> **Customize**.
3. Choose your app as the default handler for the relevant channels (e.g., Local SMS, International SMS).
4. Trigger a message from the store (for example, by placing a test order or manually sending a notification to a customer).
5. Verify that the message was successfully delivered to your phone/inbox via your chosen provider.
Once all tests pass successfully, publish your function to make it live for merchants.
1. Return to the Partner Portal and open your app dashboard.
2. Click **Start publishing your app** to make the function live and follow the standard publication process.
:::warning[Important Notes]
- **Seamless Updates:** Merchants who already have your app installed will receive the updated function capabilities automatically once published.
- **Sandbox Safety:** All edits made in the code editor are saved in a sandbox environment until you explicitly hit publish. Always test thoroughly in the preview panel before pushing changes to production!
:::