## Sign staff in to the inbox

`POST https://whatsapp.paaltech.org/api/v1/businesses/{external_id}/inbox/sign-in`

Single sign-on into the PaalChat inbox for a staff member already signed in to your
product. Send who they are and their role (`admin`, `agent` or `viewer`) - PaalChat
records or updates the member - then redirect their browser to `url`. The link works
once, within 5 minutes; ask for a new one each time. Pass `conversation_id` to open that
conversation. PaalChat never holds staff passwords. Needs the inbox enabled for the business.

Ability: `inbox.manage`

### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `external_id` | string | yes | Your own ID for the business (Multi-SKUUL - the tenant ID). Max 191 characters. Pattern `^[A-Za-z0-9._:-]+$` |

### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `staff` | object | yes |  |
| `staff.external_id` | string | yes | Your id for the staff member. Max 191 characters |
| `staff.name` | string | yes | Max 191 characters |
| `staff.email` | string | null | no | Format email |
| `staff.role` | string | yes | viewer reads; agent also replies, notes, tags and takes conversations; admin also assigns anyone. One of: `admin`, `agent`, `viewer` |
| `conversation_id` | integer | null | no | Open this conversation after signing in. |

### Request

```bash
curl --request POST \
  --url 'https://whatsapp.paaltech.org/api/v1/businesses/presec/inbox/sign-in' \
  --header "Authorization: Bearer $PAALCHAT_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "staff": {
    "external_id": "teacher-12",
    "name": "Kwame Owusu",
    "email": "owusu@presec.edu.gh",
    "role": "agent"
  },
  "conversation_id": 7
}'
```

### Responses

- **201** - The one-time link.

```json
{
  "data": {
    "url": "https://whatsapp.paaltech.org/inbox/sign-in/Xk3...64 chars",
    "expires_at": "2026-10-02T09:05:00+00:00",
    "member": {
      "external_id": "teacher-12",
      "name": "Kwame Owusu",
      "email": "owusu@presec.edu.gh",
      "role": "agent",
      "active": true,
      "last_seen_at": null
    }
  }
}
```

- **401** - unauthenticated - missing, invalid, revoked or expired token

```json
{
  "error": {"code": "unauthenticated", "message": "A valid product token is required."}
}
```

- **403** - missing_ability, or feature_disabled (the inbox is not enabled for the business).
- **404** - not_found - not yours, or does not exist

```json
{"error": {"code": "not_found", "message": "Business not found."}}
```

- **409** - business_suspended.
- **422** - validation_failed - fields are invalid; see errors.

```json
{
  "error": {
    "code": "validation_failed",
    "message": "The external id field format is invalid. (and 1 more error)"
  },
  "errors": {
    "external_id": ["The external id field format is invalid."],
    "name": ["The name field is required."]
  }
}
```

- **429** - rate_limited - over 300 requests/minute for this product

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Slow down and retry after the Retry-After header."
  }
}
```