Conversations

A conversation with Kinro is one insurance request for one business. Your agent talks to Kinro with two tools: ask_kinro tells Kinro what the user needs, and get_kinro_messages gets Kinro's messages, both new ones and the conversation so far. Kinro's messages come from Leo, Kinro's AI advisor, who says openly that it is an AI.

The loop

1. Call ask_kinro with what the user needs and the business details they have given you. Omit conversation_id on the first message.
2. Show the user every message in the result, in order.
3. Read what Kinro says will happen next. When Kinro asks something, answer from what the user has told you, ask the user the rest, and send the answers with ask_kinro. Send the user's follow-up requests the same way.
4. When Kinro says it is still working, for example pricing a quote, call get_kinro_messages with wait: true to get its next messages. Check back when Kinro says to expect news.

Kinro does not report its progress in separate fields. Its messages say what it is doing and when to expect the next step, in words written for the user and the agent alike.

Conversation IDs

The first ask_kinro call opens a conversation and returns a conversation_id, both in structuredContent and as a final text line (conversation_id: …), for clients that drop structured results.

• Pass the same conversation_id on every later ask_kinro and get_kinro_messages call in that conversation.
• Keep it with the conversation, including after your client reconnects or restarts.
• Omitting it on an ask_kinro call starts a new insurance request. Start a new one only when the user is asking about a different business.
• Never invent an ID or reuse another user's. An unknown ID never opens a conversation; the call answers that there is no conversation.

The ID is a handle, not a password or an identity check. Treat it as private to the user.

ChatGPT and Codex keep their conversations together through their own conversation metadata, so in those clients the result does not include a conversation_id.

Messages

ask_kinro's messages lists Kinro's reply as text, with any other message Kinro sent since your last call, oldest first. Show each one to the user as written; messages can contain links the user needs, such as the link to a quote. A message Kinro also sent by email or text appears here too.

Getting Kinro's messages

Call get_kinro_messages for Kinro's new messages and the conversation so far: when Kinro says it is still working, when the user asks for an update, after a lost result, or after your client reconnects.

• It returns the conversation's latest messages, oldest first: the user's messages and Kinro's, each with who sent it (from: user or kinro) and when (sent_at).
• new is true for each Kinro message you have not received before, such as a ready quote or a late reply. Show every new message to the user as written. The text result marks them Kinro, new.
• It returns 5 messages by default. Set limit, up to 100, for more or fewer; new messages are always included. has_more is true when earlier messages exist. Previously delivered messages older than the latest 100 are not available through this tool.
• Set wait: true when Kinro has said more is coming. The call returns as soon as a new message arrives, or after a short wait, about 25 seconds (60 in Codex), with the note No new messages from Kinro yet. When Kinro is waiting for the user, ask the user instead of checking again.
• It sends nothing to Kinro and starts no reply. Messages you already received stay readable, marked not new, so a reply or quote lost on the way can be read again.
• Pass the same conversation_id as for ask_kinro. ChatGPT and Codex need none.

A message is new only once. Keep calls sequential and save each result before making another call.

Updating an existing connection

Refresh your client's tool list and schemas, or reconnect the Kinro app, before using an existing connection:

• Use get_kinro_messages with wait: true wherever your integration called ask_kinro without a message or check_kinro_updates. ask_kinro now requires a message, and check_kinro_updates is no longer available.
• Read messages as an array of strings. Results no longer include status, lastMessage, or quotePending; messages no longer have kind or channel fields.
• Show quote links from the messages. show_kinro_quote and its quote card are no longer available.

A client with a cached output schema can reject a valid result after Kinro has already received your message. Do not resend it because of a schema error. Refresh the schemas, then use get_kinro_messages to read any reply the rejected result carried.

Timing

• ask_kinro returns within about 30 seconds. If Leo needs longer, the result says Kinro is still working on the message. The message has been received; do not send it again. Call get_kinro_messages with wait: true to get the reply.
• Quotes usually arrive within a few minutes of Kinro saying it is pricing one.
• Set your client's tool timeout to at least 60 seconds, or 320 seconds in Codex to allow its longer checks.

One message at a time

Each ask_kinro call sends a new message. Kinro answers the messages in a conversation one at a time:

• Do not retry a call to resend a message. If a call fails or times out, call get_kinro_messages to see whether Kinro received it, before you ask the user whether to send it again.
• Wait for the reply before sending the next message. A message sent while Kinro is still answering is refused with a note to wait.

Speaking for the user

Your agent talks to Kinro on the user's behalf, the way an assistant would on the phone with a broker. Kinro gives advice as a licensed broker, so what it hears must come from the user:

• In message, tell Kinro what the user wants, such as advice, a quote or a change to a quote, with the business facts the user has given you that Kinro needs to move forward. Write it in your own words or the user's.
• Do not paste your conversation with the user. Leave out what the user said only to you, such as which tool, connection or endpoint to use, or how to talk to Kinro.
• Answer Kinro's questions with what the user has already told you. Ask the user for anything else, then send their answers.
• Never guess a fact about the business, and do not tell Kinro what to infer. Kinro asks its own clarifying questions. On the test endpoint, a business the user has you make up counts as what the user told you: give its details as plain facts.
• Send the user's follow-up requests, such as a different limit or start date, in the same conversation.
• Never send a Social Security number, driver's license number, payment card number or password, even if the user offers one. Kinro collects anything sensitive it needs outside the chat.

When a team member is needed

Some requests need a licensed Kinro team member. Leo says so in the conversation. The conversation does not end: keep sending the user's questions and details with ask_kinro. A team member handling part of the request is not a promise of an outcome or a completion time.

Contact outside the chat

Kinro may email or text the user, for example to send a quote or follow up, but only at contact details the user shares in the conversation and agrees to be contacted at. Kinro asks for that agreement in the conversation before it first emails or texts. If the user declines, the request continues in the conversation. Messages Kinro sends by email or text also reach your agent through ask_kinro or get_kinro_messages.

When supplying a phone number, include its country code.

If the user stops replying and Kinro has no agreed way to reach them, Kinro may close the request and withdraw any open quote. A later message in the same conversation reopens it.