Prompts

Prompts are interactive questions delivered to a PROMPT channel.

Create prompts with POST /v1/prompts/new — the /new verb means create a durable resource. For MESSAGE channel chat replies, use POST /v1/messages/send instead.

Create (`POST /v1/prompts/new`)

Send application/json or multipart/form-data to the same path.

JSON body

Field	Type	Default	Notes
`channel_id`	string	`DEFAULT_PROMPT_CHANNEL_ID`	Required unless default set
`text`	string	—	Required, max 4096
`options`	string[]	`[]`	Max 10 items (3 on WhatsApp/Messenger), each max 64 chars
`allow_text`	boolean	`false`	Allow free-text replies
`callback_url`	string	—	Validated HTTP(S) URL
`correlation_id`	string	—	Echoed in answer callback
`ttl_sec`	int	`3600`	0–604800 (7 days)
`media_url`	string	—	Remote attachment URL
`media_path`	string	—	Local path under `MEDIA_ALLOWED_DIR`

Multipart form (file upload)

Use the same logical fields as form fields. Send the attachment as file. options may be a JSON string. Do not combine file and media_url.

Only one media source is allowed among media_url, media_path, and upload file.

Default content type for uploads is image/jpeg. Max size is governed by MAX_MEDIA_SIZE_MB (default 2).

Text replies

When allow_text is true, humans can reply in the chat with:


ID:#123 my free-text answer

Also accepted: ID:123 …, ID #123 …, ID-123 … (case-insensitive).

Greenlight records answer.type = "text" and posts a confirmation in the thread.

States

State	Meaning
`PENDING`	Waiting for an answer
`ANSWERED`	Button or text reply recorded
`EXPIRED`	TTL elapsed

Background expiry runs periodically. CLEAN_ON_BOOT can clear stale state on startup.

List


GET /v1/prompts?state=pending
GET /v1/prompts?state=all&limit=100

state: pending (default) | answered | expired | all. limit: 1–200 (default 50).

Fetch by id

IDs look like #123 — URL-encode the # as %23:


GET /v1/prompts/%23123