Conversation Openers

Generate three opener message candidates grounded in the recipient's actual photos and bio, tagged with a style label.

POST /v1/conversation/openers

Request

{
  "sender": {
    "id": "usr_sender",
    "name": "Alex",
    "preferences": { "lifestyle": ["…"] }
  },
  "recipient": {
    "id": "usr_recipient",
    "photos": ["https://…/r1.jpg", "https://…/r2.jpg"],
    "bio": "Marathon runner, weekend potter, …"
  },
  "tone": "playful",
  "count": 3
}

Field	Type	Required	Notes
sender	object	yes	At minimum id and name
recipient	object	yes	At minimum id, photos, bio
tone	enum	no	playful (default), warm, direct, witty
count	int	no	1–5; default 3

Response

{
  "request_id": "req_01H…",
  "openers": [
    {
      "text": "Marathon runner with a pottery wheel in the background — pacing yourself or just collecting hobbies that ruin your hands?",
      "style": "playful_observation",
      "length": 117
    },
    {
      "text": "I see two pieces of pottery in your second photo and I have so many questions.",
      "style": "open_question",
      "length": 79
    },
    {
      "text": "If you ran a marathon and threw a pot in the same day, I'd be impressed. If you've done both this week, I want to know your secret.",
      "style": "shared_interest",
      "length": 132
    }
  ]
}

Each opener is annotated with a style label. The five styles are:

• playful_observation — light, observational, no question
• open_question — invites a reply by asking
• photo_callback — references a specific element in the photos
• shared_interest — calls out something the sender and recipient have in common
• confident_direct — short, declarative, no hedging

Latency

P50 ~ 8–12 s, P95 ~ 18–22 s. Generation streams as it produces tokens, so clients can show partial output.

For UX best practice: show a "Generating openers…" loading state and reveal the three options together when complete.

Use it for

• "Suggest an opener" button on the chat compose screen
• A/B test which style your users actually send vs. swipe past
• Wire the POST /v1/events endpoint to report opener_sent and conversation_reply and the partner portal will compute reply rate by style

Common errors

Code	Why
invalid_recipient	Recipient missing required fields (photos + bio)
unsafe_content	Recipient photo or bio failed content safety
quota_exceeded	Free tier monthly cap reached — see Pricing