# Yemen Snack Food integration (no client code changes)

This application exposes `POST /api/whatsapp/send-text`, compatible with the active Evolution-style text sender in the archived Yemen Snack Food source. Yemen Snack's PHP code remains unchanged; only its admin settings need updating.

## Enable a device

1. Deploy the new code and run `php artisan migrate --force`. The deployment workflow runs this automatically.
2. Connect the intended WhatsApp device in this application's admin panel.
3. Open **Devices → Edit → External WhatsApp API** and enable **Enable external API**. A separate integration key is generated. Save the device.
4. Reveal/copy **Integration API key** and copy the **Sending endpoint** shown on the form.
5. In Yemen Snack's admin configuration, set:

| Yemen Snack field | Value |
| --- | --- |
| `site_system_whatsapp_url` | `https://campaigns.platformdgtl.org/api/whatsapp/send-text` (or the endpoint shown in this application's device form) |
| `site_system_whatsapp_appkey` | The integration key from step 4 |
| `site_system_whatsapp_authkey` | Not used by its active text sender |

The integration key is not the Evolution Go instance token or global admin key. It is bound to one device and cannot select another device via request parameters. Keys are encrypted at rest, excluded from model serialization, and looked up using a SHA-256 hash. Preserve Laravel's existing `APP_KEY`.

To revoke access, turn off **Enable external API** and save. To rotate, click the generation icon beside the key, confirm, save, and update Yemen Snack's App key. The previous key stops working immediately after saving.

## Request and response

```http
POST /api/whatsapp/send-text
Content-Type: application/json
apikey: YOUR_INTEGRATION_KEY
```

```json
{"number":"967777123456","text":"Hello"}
```

Use international numbers including the country code. A leading `+`, spaces, parentheses, and hyphens are accepted and normalized. Group addresses, empty text, and media/file requests are not supported by this endpoint. It uses the provider already selected on the device, including Evolution Go.

The request sends synchronously to the provider once. Provider acceptance returns HTTP 200:

```json
{
  "status": true,
  "message_status": "Success",
  "key": {"id": "ACTUAL_PROVIDER_MESSAGE_ID"},
  "message": {"conversation": "Hello"},
  "outcome": "accepted"
}
```

`key.id` is null if the provider does not return an ID; no artificial provider ID is generated. The truthy `status` and object-shaped `message` match Yemen Snack's response parser. Acceptance is not confirmed recipient delivery. These transactional sends do not create campaign recipients or change campaign counters.

Failures always return JSON with `status: false`, `message_status: "error"`, an `error` string, and an `outcome`. They never return Go's string-shaped `message` field, which the legacy parser does not handle.

| HTTP status | Meaning |
| --- | --- |
| 401 | Missing, wrong, revoked, or disabled integration key |
| 422 | Invalid number/text or unsupported media |
| 429 | IP/device limit, device busy, pacing limit, or explicit provider rate rejection |
| 503 | The assigned device is inactive |
| 502 | Provider rejected the message |
| 504 | Sending timed out or was interrupted; outcome is `unknown` |

Limits are 120 requests per minute per client IP and 60 authenticated requests per minute per device. The endpoint also shares the campaign device lock and `WHATSAPP_SEND_INTERVAL` cooldown. Busy requests are rejected rather than silently queued: Yemen Snack expects an immediate result. Do not blindly retry `unknown` outcomes, because the provider may already have accepted the message. Repeating identical requests is not deduplicated: the unchanged Yemen Snack client sends no idempotency key.

The API requires no browser session or CSRF token; authentication is through the `apikey` header. Use HTTPS. Neither the key nor provider credentials should appear in URLs. No production integration key has been generated or enabled merely by deploying this feature.

## Verification

`tests/Feature/WhatsAppCompatibilityApiTest.php` checks the unchanged Yemen Snack success expression, device isolation, key encryption/rotation/revocation, invalid requests, rate limiting, campaign lock compatibility, and uncertain timeouts with HTTP fakes. Live sending from the deployed Yemen Snack application still requires an end-to-end check.
