# Washeej Legacy Device API (`/device-api/v1`)

HTML UI: https://staging-mobile.washeej.com/device-api-documentation/getting-started

> Prefer API v1 for new integrations: https://staging-mobile.washeej.com/api-v1-documentation.md

- **Base URL:** `https://staging-mobile.washeej.com/device-api/v1`

## Pages

- [Device Introduction](https://staging-mobile.washeej.com/device-api-documentation/getting-started)
- [Device Authentication](https://staging-mobile.washeej.com/device-api-documentation/authentication)
- [Instances](https://staging-mobile.washeej.com/device-api-documentation/instances)
- [Device Messages](https://staging-mobile.washeej.com/device-api-documentation/messages)
- [Cloud vs Device](https://staging-mobile.washeej.com/device-api-documentation/comparison)
- [Migrate Device to v1](https://staging-mobile.washeej.com/device-api-documentation/migrate)

## Endpoints

### GET `/instances`

- **Key:** `instances.list`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/instances`
- **Auth:** public / none
- **Summary:** List Device/QR instances for the account.

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
     -H "X-Api-Secret: YOUR_API_SECRET" \
     https://staging-mobile.washeej.com/device-api/v1/instances
```

API v1 equivalent: `GET /v1/devices`

### POST `/instances`

- **Key:** `instances.create`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/instances`
- **Auth:** public / none
- **Summary:** Create a new device instance.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Display name for the instance. |

```bash
curl -X POST https://staging-mobile.washeej.com/device-api/v1/instances \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"My WhatsApp"}'
```

API v1 equivalent: `Create channels in dashboard; list via GET /v1/devices`

### GET `/instances/{instance_id}`

- **Key:** `instances.show`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/instances/{instance_id}`
- **Auth:** public / none
- **Summary:** Get a single instance.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `instance_id` | string | yes | Instance unique ID. |

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
     -H "X-Api-Secret: YOUR_API_SECRET" \
     https://staging-mobile.washeej.com/device-api/v1/instances/YOUR_INSTANCE_ID
```

API v1 equivalent: `GET /v1/devices + GET /v1/devices/{id}/status`

### DELETE `/instances/{instance_id}`

- **Key:** `instances.delete`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/instances/{instance_id}`
- **Auth:** public / none
- **Summary:** Disconnect and delete an instance.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `instance_id` | string | yes | Instance unique ID. |

```bash
curl -X DELETE https://staging-mobile.washeej.com/device-api/v1/instances/YOUR_INSTANCE_ID \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"
```

### GET `/instances/{instance_id}/qr`

- **Key:** `instances.qr`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/instances/{instance_id}/qr`
- **Auth:** public / none
- **Summary:** Get QR code image for pairing.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `instance_id` | string | yes | Instance unique ID. |

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
     -H "X-Api-Secret: YOUR_API_SECRET" \
     https://staging-mobile.washeej.com/device-api/v1/instances/YOUR_INSTANCE_ID/qr
```

API v1 equivalent: `POST /v1/devices/{id}/qr`

### POST `/instances/{instance_id}/reconnect`

- **Key:** `instances.reconnect`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/instances/{instance_id}/reconnect`
- **Auth:** public / none
- **Summary:** Request a fresh QR session when disconnected.

```bash
curl -X POST https://staging-mobile.washeej.com/device-api/v1/instances/YOUR_INSTANCE_ID/reconnect \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"
```

### GET `/instances/{instance_id}/status`

- **Key:** `instances.status`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/instances/{instance_id}/status`
- **Auth:** public / none
- **Summary:** Connection status: pending, connected, disconnected.

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
     -H "X-Api-Secret: YOUR_API_SECRET" \
     https://staging-mobile.washeej.com/device-api/v1/instances/YOUR_INSTANCE_ID/status
```

API v1 equivalent: `GET /v1/devices/{id}/status`

### POST `/messages/text`

- **Key:** `messages.text`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/messages/text`
- **Auth:** public / none
- **Summary:** Send a text message via a connected QR device.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `instance_id` | string | yes | Device instance ID (always required). |
| `to` | string | yes | Recipient with country code, no +. |
| `text` | string | yes | Message body (max 4096). |

Notes:

- Every Device API call requires instance_id.

```bash
curl -X POST https://staging-mobile.washeej.com/device-api/v1/messages/text \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "YOUR_INSTANCE_ID",
    "to": "966500000000",
    "text": "Hello via QR device"
  }'
```

API v1 equivalent: `POST /v1/messages with device whatsapp_account_id`

### POST `/messages/image`

- **Key:** `messages.image`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/messages/image`
- **Auth:** public / none
- **Summary:** Send an image with optional caption.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `instance_id` | string | yes | Device instance ID. |
| `to` | string | yes | Recipient phone. |
| `image_url` | url | yes | Direct image URL. |
| `caption` | string | no | Optional caption. |

```bash
curl -X POST https://staging-mobile.washeej.com/device-api/v1/messages/image \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"instance_id":"YOUR_INSTANCE_ID","to":"966500000000","image_url":"https://example.com/a.jpg","caption":"Photo"}'
```

### POST `/messages/video`

- **Key:** `messages.video`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/messages/video`
- **Auth:** public / none
- **Summary:** Send a video. Same shape as image, use video_url.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `instance_id` | string | yes | Device instance ID. |
| `to` | string | yes | Recipient phone. |
| `video_url` | url | yes | Direct video URL. |
| `caption` | string | no | Optional caption. |

```bash
curl -X POST https://staging-mobile.washeej.com/device-api/v1/messages/video \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"instance_id":"YOUR_INSTANCE_ID","to":"966500000000","video_url":"https://example.com/a.mp4"}'
```

### POST `/messages/document`

- **Key:** `messages.document`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/messages/document`
- **Auth:** public / none
- **Summary:** Send a document (PDF preview when filename ends with .pdf).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `instance_id` | string | yes | Device instance ID. |
| `to` | string | yes | Recipient phone. |
| `document_url` | url | yes | Document URL. |
| `filename` | string | yes | Display filename with extension. |
| `caption` | string | no | Optional caption. |

```bash
curl -X POST https://staging-mobile.washeej.com/device-api/v1/messages/document \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"instance_id":"YOUR_INSTANCE_ID","to":"966500000000","document_url":"https://example.com/invoice.pdf","filename":"invoice.pdf"}'
```

### POST `/messages/audio`

- **Key:** `messages.audio`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/messages/audio`
- **Auth:** public / none
- **Summary:** Send an audio / voice file.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `instance_id` | string | yes | Device instance ID. |
| `to` | string | yes | Recipient phone. |
| `audio_url` | url | yes | Direct audio URL. |

```bash
curl -X POST https://staging-mobile.washeej.com/device-api/v1/messages/audio \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"instance_id":"YOUR_INSTANCE_ID","to":"966500000000","audio_url":"https://example.com/note.ogg"}'
```

### POST `/messages/location`

- **Key:** `messages.location`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/messages/location`
- **Auth:** public / none
- **Summary:** Send a location pin.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `instance_id` | string | yes | Device instance ID. |
| `to` | string | yes | Recipient phone. |
| `latitude` | number | yes | Latitude (-90 to 90). |
| `longitude` | number | yes | Longitude (-180 to 180). |
| `name` | string | no | Place name. |
| `address` | string | no | Address text. |

```bash
curl -X POST https://staging-mobile.washeej.com/device-api/v1/messages/location \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"instance_id":"YOUR_INSTANCE_ID","to":"966500000000","latitude":24.7136,"longitude":46.6753,"name":"Riyadh"}'
```

### GET `/messages/{message_id}/status`

- **Key:** `messages.status`
- **URL:** `https://staging-mobile.washeej.com/device-api/v1/messages/{message_id}/status`
- **Auth:** public / none
- **Summary:** Lookup delivery status for a previously sent message ID.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `message_id` | string | yes | Message ID returned from send endpoints. |

Notes:

- Status tracking may be limited depending on device channel capabilities.

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
     -H "X-Api-Secret: YOUR_API_SECRET" \
     https://staging-mobile.washeej.com/device-api/v1/messages/MESSAGE_ID/status
```