Conversations

This page is for the developer who files conversations in your case management or records system.

With it you can list your organisation's conversations, and read one with its transcript, its facts and its summary.

Before you start

1. Where to send calls. The base address is https://app.inmywords.chat/api/integrations/v1/.
2. Send your key every time. Every request carries Authorization: Bearer imw_<64 hex characters>, the key of a connection your organisation has made.
3. The scopes you need. conversations:read lets you read a conversation, its transcript and its facts. summaries:read lets you read its summary.
4. You see only your own organisation. A conversation of another organisation answers 404, the same as one that does not exist.
5. How values are written. A conversation's id is 32 lowercase hex characters. Other ids are strings of digits, such as "57". Times are ISO 8601 in UTC, and field names are snake_case.

A conversation's words come in two languages: what each person said, and the translation the other person was shown.

When a conversation ends, the conversation.ended webhook event is sent. When its summary is written or rewritten, summary.ready is sent.

What you can call

What a conversation holds

List your conversations

Conversations come newest first. limit is 50 by default and 100 at most, and a larger value is reduced to 100.

To read the next page, pass the next_cursor of the page before as cursor. next_cursor is null on the last page.

To fetch only what has changed, give updated_since an ISO 8601 time and you get back only the conversations changed after it. A change is anything that changes the conversation itself, a turn or its ending included, or its summary being written.

A bad limit, cursor or updated_since answers 400 invalid_request.

curl "https://app.inmywords.chat/api/integrations/v1/conversations?limit=2" \
  -H "Authorization: Bearer imw_3f9c..."

{
  "data": [
    {
      "id": "3f9a1c0e7b2d4e6f8a1b2c3d4e5f6a7b",
      "started_at": "2026-10-02T09:14:03Z",
      "ended_at": "2026-10-02T09:41:47Z",
      "languages": {"operator": "en", "service_user": "so"},
      "case_id": "1207",
      "group": {"id": "57", "name": "Housing advice"},
      "operator": {"id": "1842", "display_name": "Fiona Maclean"},
      "turn_count": 38,
      "has_summary": true
    },
    {
      "id": "9b8e2f71c04a4d3eb5a6c7d8e9f0a1b2",
      "started_at": "2026-10-02T08:02:11Z",
      "ended_at": null,
      "languages": {"operator": "en", "service_user": "pl"},
      "case_id": null,
      "group": {"id": "57", "name": "Housing advice"},
      "operator": {"id": "1790", "display_name": "Tom Gallagher"},
      "turn_count": 12,
      "has_summary": false
    }
  ],
  "next_cursor": "WyIyMDI2LTEwLTAyIDA5OjAyOjExIiwzNzEyXQ"
}

Read a conversation

curl https://app.inmywords.chat/api/integrations/v1/conversations/3f9a1c0e7b2d4e6f8a1b2c3d4e5f6a7b \
  -H "Authorization: Bearer imw_3f9c..."

You get back {"data": {...}}, holding one conversation with the fields above.

Read the transcript

Turns come in the order they were said. Each one carries the words as said and the translation the other person was shown, each with its language.

curl https://app.inmywords.chat/api/integrations/v1/conversations/3f9a1c0e7b2d4e6f8a1b2c3d4e5f6a7b/transcript \
  -H "Authorization: Bearer imw_3f9c..."

{
  "data": [
    {
      "speaker": "operator",
      "said": {"text": "Can you tell me when the letter arrived?", "language": "en"},
      "shown": {"text": "Ma ii sheegi kartaa goorta warqaddu timid?", "language": "so"},
      "score": 96,
      "said_at": "2026-10-02T09:15:20Z"
    },
    {
      "speaker": "service_user",
      "said": {"text": "Warqaddu waxay timid Isniinta.", "language": "so"},
      "shown": {"text": "The letter came on Monday.", "language": "en"},
      "score": 98,
      "said_at": "2026-10-02T09:15:41Z"
    }
  ]
}

Read the facts

The facts are what the conversation recorded about the person it was held with.

curl https://app.inmywords.chat/api/integrations/v1/conversations/3f9a1c0e7b2d4e6f8a1b2c3d4e5f6a7b/facts \
  -H "Authorization: Bearer imw_3f9c..."

{
  "data": [
    {"key": "household_size", "category": "household", "value": "3", "set_at": "2026-10-02T09:18:02Z"},
    {"key": "letter_received", "category": "housing", "value": "Monday 28 September", "set_at": "2026-10-02T09:15:44Z"}
  ]
}

Read the summary

curl https://app.inmywords.chat/api/integrations/v1/conversations/3f9a1c0e7b2d4e6f8a1b2c3d4e5f6a7b/summary \
  -H "Authorization: Bearer imw_3f9c..."

{
  "data": {
    "text": "The client received an eviction notice on Monday 28 September and lives with two children.",
    "language": "en",
    "written_at": "2026-10-02T09:43:10Z"
  }
}

A summary is written in English after the conversation ends, where your organisation has conversation reviews switched on. A conversation with no summary yet answers 404 not_found.

When something goes wrong

Every error comes back as {"error": {"code": "...", "message": "..."}} with the HTTP status.

{"error": {"code": "scope_missing", "message": "This connection does not hold summaries:read."}}