# Questions

Your shop's WhatsApp assistant answers what it can from your products, prices, delivery and payment settings, and the **About your shop** notes. When a customer asks something it can't answer — "is the bread fresh today?", "can you deliver tomorrow at 8?", a complaint, a photo — it tells them it's checking, and creates a **question** for the shop.

The customer never leaves the conversation. You answer in a few words; the assistant turns that into the reply, in the customer's language and your shop's voice, keeps the sale going (offering the closest product when something is out, for example), and remembers it for the rest of the chat.

Questions can be answered from the owner's WhatsApp (just type the answer), from the dashboard, or with this API — which is how your own support tool or an AI agent can take over the shop's inbox.

## The question object

```json
{
  "id": "q_…",
  "object": "question",
  "status": "answered",
  "customer": { "id": "ct_…", "name": "Wanjiku Kamau", "phone": "+254712345678" },
  "question": "do you have Brookside milk?",
  "summary": "Asks whether the shop stocks Brookside milk.",
  "has_photo": false,
  "answer": "no brookside, just general milk",
  "reply": "We don't stock Brookside, but we have fresh Maziwa 500ml at KES 60 🥛 Shall I add one?",
  "suggested_knowledge": "We don't stock Brookside milk; we sell general fresh milk.",
  "answered_via": "api",
  "created": 1792750159,
  "answered": 1792750301
}
```

| Field | |
|---|---|
| `status` | `open` (waiting), `answered`, or `dismissed` (no reply needed, or the owner chatted directly). |
| `question` | The customer's own words. Follow-ups within an hour are added to the same question. |
| `reply` | What the customer was actually sent. |
| `suggested_knowledge` | A lasting fact from your answer, worth adding to **About your shop** so the assistant answers it itself next time. `null` if the answer was only about this customer or today. |

## List questions

`GET /v1/questions?status=open` — newest first, [paginated](https://kibanda.africa/docs/pagination). `status` is `open` (default), `answered`, `dismissed` or `all`.

```bash
curl https://api.kibanda.africa/v1/questions -H "Authorization: Bearer kb_test_…"
```

## Answer a question

`POST /v1/questions/{id}/answer`

| Parameter | |
|---|---|
| `text` | **Required.** Your answer, in your own words. |
| `as_is` | `true` sends `text` to the customer exactly as written, instead of letting the assistant word it. |
| `save_knowledge` | `true` also adds the `suggested_knowledge` to **About your shop**. |

```bash
curl https://api.kibanda.africa/v1/questions/q_…/answer \
  -H "Authorization: Bearer kb_test_…" \
  -d text="no brookside, just general milk"
```

Returns the answered question, with the `reply` that was sent. Errors: `question_not_open` (already answered or dismissed), `outside_messaging_window` (the customer last wrote over 24 hours ago, so WhatsApp won't deliver a free-form message).

Amounts in the assistant's wording must come from your catalog, the customer's cart, your shop's facts or your answer; if the assistant would state any other amount, your words are sent as they are instead.

## Dismiss a question

`POST /v1/questions/{id}/dismiss` — no reply is needed. The customer isn't messaged.

## Events

| Event | When |
|---|---|
| `question.created` | A customer asked something only the shop can answer. Your agent can answer it straight away. |
| `question.answered` | It was answered (from WhatsApp, the dashboard or the API). |
| `question.dismissed` | It was dismissed. |

An agent loop is just: subscribe to `question.created`, decide the answer (or escalate to a person), `POST …/answer`.