|
1 | | -<img src="https://www.seven.io/wp-content/uploads/Logo.svg" width="250" /> |
| 1 | +<p align="center"> |
| 2 | + <img src="https://www.seven.io/wp-content/uploads/Logo.svg" width="250" alt="seven logo" /> |
| 3 | +</p> |
2 | 4 |
|
| 5 | +<h1 align="center">seven SMS for Zammad</h1> |
3 | 6 |
|
4 | | -# Zammad Package for seven.io |
5 | | -This package adds seven as a SMS provider for two-way messaging. |
| 7 | +<p align="center"> |
| 8 | + Two-way SMS messaging for Zammad via the seven gateway. |
| 9 | +</p> |
6 | 10 |
|
7 | | -Tested with Zammad v6.x. |
| 11 | +<p align="center"> |
| 12 | + <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-teal.svg" alt="MIT License" /></a> |
| 13 | + <img src="https://img.shields.io/badge/Zammad-v6.x-blue" alt="Zammad v6.x" /> |
| 14 | + <img src="https://img.shields.io/badge/version-2.3.0-green" alt="Version 2.3.0" /> |
| 15 | +</p> |
| 16 | + |
| 17 | +--- |
| 18 | + |
| 19 | +## Features |
| 20 | + |
| 21 | +- **Outbound SMS** — Send SMS notifications directly from Zammad tickets |
| 22 | +- **Inbound SMS** — Receive SMS and automatically create or update tickets |
| 23 | +- **Custom Sender ID** — Configure a sender name or number for outbound messages |
| 24 | + |
| 25 | +## How it works |
| 26 | + |
| 27 | +``` |
| 28 | + ┌─────────────┐ |
| 29 | + │ Zammad │ |
| 30 | + │ Ticket │ |
| 31 | + └──────┬──────┘ |
| 32 | + │ |
| 33 | + ┌────────────────┼────────────────┐ |
| 34 | + │ │ │ |
| 35 | + ▼ ▼ ▼ |
| 36 | + ┌───────────┐ ┌────────────┐ ┌────────────────┐ |
| 37 | + │ Outbound │ │ Inbound │ │ Notification │ |
| 38 | + │ (Reply) │ │ (Webhook) │ │ (Trigger) │ |
| 39 | + └─────┬─────┘ └─────┬──────┘ └───────┬────────┘ |
| 40 | + │ │ │ |
| 41 | + ▼ ▼ ▼ |
| 42 | + ┌─────────────────────────────────────────────┐ |
| 43 | + │ seven SMS Gateway API │ |
| 44 | + │ gateway.seven.io/api/sms │ |
| 45 | + └──────────────────┬──────────────────────────┘ |
| 46 | + │ |
| 47 | + ▼ |
| 48 | + ┌───────────┐ |
| 49 | + │ Customer │ |
| 50 | + │ Phone │ |
| 51 | + └───────────┘ |
| 52 | +``` |
| 53 | + |
| 54 | +## Prerequisites |
| 55 | + |
| 56 | +- Zammad v6.x (self-hosted) |
| 57 | +- A [seven account](https://www.seven.io/) with API key ([How to get your API key](https://help.seven.io/en/api-key-access)) |
8 | 58 |
|
9 | 59 | ## Installation |
10 | | -1. Download **seven-sms.szpm** file from [Latest Releases](https://github.com/seven-io/zammad/releases/latest "Latest Releases") |
11 | | -2. Open up your Zammad **Dashboard** |
12 | | -3. Click on **Admin**, navigate to **Manage->System->Packages** and press **Choose File** |
13 | | -4. Locate the downloaded **seven-sms.szpm** and click **Install Package** |
14 | | -5. Execute as *zammad* user: `zammad run rake zammad:package:migrate && zammad run rake assets:precompile && systemctl restart zammad` |
15 | | -6. Go to **Manage->Channels->SMS->SMS Notification** and choose **seven** |
16 | | -7. Type in your [API Key](https://help.seven.io/en/api-key-access), test and you are ready to go |
| 60 | + |
| 61 | +### Step 1: Upload the package |
| 62 | + |
| 63 | +Download **seven-sms.szpm** from the [latest release](https://github.com/seven-io/zammad/releases/latest). |
| 64 | + |
| 65 | +In Zammad, navigate to **Admin > System > Packages**, click **Choose File** and select the downloaded `.szpm` file, then click **Install Package**. |
| 66 | + |
| 67 | +<details> |
| 68 | +<summary>Screenshot: Package Management</summary> |
| 69 | + |
| 70 | + |
| 71 | +</details> |
| 72 | + |
| 73 | +<details> |
| 74 | +<summary>Screenshot: Package installed</summary> |
| 75 | + |
| 76 | + |
| 77 | +</details> |
| 78 | + |
| 79 | +### Step 2: Finalize installation |
| 80 | + |
| 81 | +> **Important:** This step is required! Without it, the plugin will not appear in the SMS provider selection. |
| 82 | +
|
| 83 | +Run these commands on your Zammad server as the *zammad* user: |
| 84 | + |
| 85 | +```bash |
| 86 | +zammad run rake zammad:package:migrate |
| 87 | +zammad run rake assets:precompile |
| 88 | +systemctl restart zammad |
| 89 | +``` |
| 90 | + |
| 91 | +### Step 3: Configure SMS Notification |
| 92 | + |
| 93 | +Navigate to **Channels > SMS** and click **New** under *SMS Notification*. Select **seven** as the provider, enter your API key and optionally set a sender ID. |
| 94 | + |
| 95 | +<details> |
| 96 | +<summary>Screenshot: SMS Channel overview</summary> |
| 97 | + |
| 98 | + |
| 99 | +</details> |
| 100 | + |
| 101 | +<details> |
| 102 | +<summary>Screenshot: Configure SMS Notification</summary> |
| 103 | + |
| 104 | + |
| 105 | +</details> |
| 106 | + |
| 107 | +### Step 4: Test |
| 108 | + |
| 109 | +Click **Test** to verify the connection. You should see a "SMS successfully sent" confirmation. |
| 110 | + |
| 111 | +<details> |
| 112 | +<summary>Screenshot: Test SMS provider</summary> |
| 113 | + |
| 114 | + |
| 115 | +</details> |
| 116 | + |
| 117 | +<details> |
| 118 | +<summary>Screenshot: Success</summary> |
| 119 | + |
| 120 | + |
| 121 | +</details> |
| 122 | + |
| 123 | +<details> |
| 124 | +<summary>Screenshot: Final result</summary> |
| 125 | + |
| 126 | + |
| 127 | +</details> |
| 128 | + |
| 129 | +## Inbound SMS (Webhook) |
| 130 | + |
| 131 | +To receive incoming SMS as Zammad tickets: |
| 132 | + |
| 133 | +1. Set up a [webhook at seven](https://help.seven.io/en/articles/9582203-how-do-i-receive-sms) — make sure the format is set to **JSON** |
| 134 | +2. Point the webhook URL to your Zammad instance |
| 135 | +3. Incoming SMS will automatically create new tickets or append to existing conversations |
17 | 136 |
|
18 | 137 | ## Usage |
19 | 138 |
|
20 | | -Please refer to the official [documentation](https://admin-docs.zammad.org/en/6.1/channels/sms.html) over at Zammad. |
| 139 | +For general SMS usage in Zammad, refer to the official [Zammad SMS documentation](https://admin-docs.zammad.org/en/6.1/channels/sms.html). |
21 | 140 |
|
22 | | -### Inbound messages |
23 | | -When [setting up a webhook](https://help.seven.io/en/articles/9582203-how-do-i-receive-sms) at seven, make sure that it is of type `JSON`. |
| 141 | +## Troubleshooting |
24 | 142 |
|
| 143 | +| Problem | Solution | |
| 144 | +|---|---| |
| 145 | +| Plugin not visible after install | Run the post-install commands from Step 2 and restart Zammad | |
| 146 | +| SMS sending fails | Check your API key in the seven [dashboard](https://app.seven.io/) and verify your account balance | |
| 147 | +| Inbound SMS not creating tickets | Ensure the webhook at seven is set to type **JSON** and the URL is reachable | |
25 | 148 |
|
26 | 149 | ## Support |
27 | 150 |
|
28 | 151 | Need help? Feel free to [contact us](https://www.seven.io/en/company/contact/). |
29 | | - |
30 | | -[](LICENSE) |
|
0 commit comments