AI File Summaries

When a customer sends an image or a PDF, SendSeven can describe it in plain text: what the image shows and any text in it, or a summary and the key facts of a PDF. Your team sees the summary under the file in the conversation, and you can read it through the API.

This covers files sent as chat messages and files attached to emails a customer sent you (see Email attachments).

Summaries come from two places:

Conversational Agents. When an agent reads a customer's file to answer, the summary it made is kept and shown to your team at no extra cost.
On demand. For an inbound image or PDF without a summary, a team member (or your integration) can request one. This costs AI credits: 2 per image, 3 per PDF, from the same pool as your other AI usage (see AI credits).

AI file summaries are available when AI features are enabled for the workspace (Professional, Scale and Enterprise, with AI features switched on in the workspace settings). When AI features are off, the summary fields are always empty and the endpoints return 403.

Untrusted content

The summary text is generated from a file your customer sent. Treat it as untrusted plain text: never render it as HTML or Markdown, never follow links in it automatically, and never use it as instructions for another system. It is AI-generated and may be inaccurate.

Attachment fields on messages

Every attachment in a message response (GET /api/v1/messages, GET /api/v1/messages/{message_id}) has three extra fields:

Field	Type	Meaning
`ai_summary`	object or `null`	The summary, see Summary object. `null` when there is none or AI features are off.
`ai_summary_available`	boolean	`true` when you can request a summary with `POST /attachments/{id}/summary`: AI features are on, the file is a supported inbound image or PDF, and there is no finished (`ok`) or running (`pending`) summary. A `failed` summary can be requested again.
`ai_summary_credits`	integer or `null`	AI credits an on-demand summary of this file costs (`2` image, `3` PDF). `null` when `ai_summary_available` is `false`.

{
  "id": "6f1c0d2e-...",
  "direction": "inbound",
  "message_type": "image",
  "attachments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "receipt.jpg",
      "content_type": "image/jpeg",
      "file_size": 184320,
      "url": "https://...",
      "ai_summary": null,
      "ai_summary_available": true,
      "ai_summary_credits": 2
    }
  ]
}

Real-time payloads may omit these fields. Treat a missing field like null / false.

Summary object

{
  "status": "ok",
  "kind": "pdf",
  "text": "SUMMARY: Invoice from ...\nKEY FACTS:\n- Total: EUR 1,240.00\n- Due: 2026-11-01",
  "sections": [
    { "key": "summary", "text": "Invoice from ..." },
    { "key": "key_facts", "text": "- Total: EUR 1,240.00\n- Due: 2026-11-01" }
  ],
  "pages_read": 10,
  "pages_total": 34,
  "truncated": true,
  "model": "gemini-flash-lite",
  "source": "on_demand",
  "created_at": "2026-10-06T08:00:00Z",
  "updated_at": "2026-10-06T08:00:07Z"
}

Field	Meaning
`status`	`ok` (ready), `pending` (being generated), `failed` (generation failed, you can request it again).
`kind`	`image` or `pdf`.
`text`	The full plain-text summary.
`sections`	The summary split into parts: `description` and `text` for images, `summary` and `key_facts` for PDFs. Empty when it could not be split; show `text` instead.
`pages_read`, `pages_total`, `truncated`	PDFs only. Only the first 10 pages are read; `truncated` is `true` when the PDF is longer. `null` / `false` for images.
`model`	The AI model that made the summary.
`source`	`agent` (made while a Conversational Agent read the file) or `on_demand` (requested by your team or the API).
`created_at`, `updated_at`	UTC timestamps.

Get a summary

GET /api/v1/attachments/{attachment_id}/summary

Required scope: messages:read

Returns the summary object.

curl https://api.sendseven.com/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000/summary \
  -H "Authorization: Bearer $SENDSEVEN_TOKEN"

Status	Meaning
`200`	The summary (any `status`).
`403` `feature_disabled`	AI features are off for the workspace.
`404` `attachment_not_found`	Unknown attachment, or one you cannot see (other workspace, or a conversation outside your inboxes).
`404` `summary_not_found`	The attachment has no summary yet.

Request a summary

POST /api/v1/attachments/{attachment_id}/summary

Required scope: conversations:update. No request body.

Works for files a customer sent (inbound messages): images up to 10 MB and PDFs up to 20 MB (the first 10 pages are read). Videos, audio, stickers and other file types are not supported.

The call is idempotent: requesting a summary that already exists returns it without charging again.

curl -X POST https://api.sendseven.com/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000/summary \
  -H "Authorization: Bearer $SENDSEVEN_TOKEN"

{
  "attachment_id": "550e8400-e29b-41d4-a716-446655440000",
  "summary": { "status": "ok", "kind": "image", "text": "DESCRIPTION: ...", "...": "..." },
  "credits_charged": 2
}

Status	Meaning	`credits_charged`
`201`	A new summary was created.	`2` (image) or `3` (PDF)
`200`	A summary already existed and is returned.	`0`
`202`	A summary is being generated right now (`summary.status` is `pending`). Poll `GET .../summary` every few seconds.	`0`
`403` `feature_disabled`	AI features are off for the workspace.	-
`404` `attachment_not_found`	Unknown attachment, or one you cannot see.	-
`422` `attachment_not_summarizable`	Not an inbound image or PDF, or the file is too large.	-
`429` `rate_limit_exceeded`	More than 30 requests per minute for your user or API key, or more than 60 per minute for the whole workspace. Retry after the `Retry-After` header.	-
`502` `summary_failed`	The summary could not be generated. Nothing is charged; you can try again.	-
`503` `rate_limit_unavailable`	Temporarily unavailable. Retry shortly.	-

Error bodies have the form {"detail": {"code": "...", "message": "..."}}. Rate-limit responses (429, 503) use {"detail": {"error": "rate_limit_exceeded" | "rate_limit_unavailable", ...}}.

Two different 403 responses can occur:

AI features are off: {"detail": {"code": "feature_disabled", "feature": "ai_features"}}.
Your token lacks the scope: {"detail": "Missing required permission(s): conversations:update"} (a plain string).

Team Chat files

Images and PDFs shared in Team Chat channels, thread replies and direct messages can be summarized too, at the same price (2 AI credits per image, 3 per PDF) and with the same size limits. Team Chat messages carry the same three fields on each entry of attachments: ai_summary, ai_summary_available and ai_summary_credits.

Summaries are available in your own workspace's channels and direct messages. Channels shared across workspaces and external (guest) channels never offer them.

GET  /api/v1/team-chat/messages/{message_id}/attachments/{attachment_id}/summary
POST /api/v1/team-chat/messages/{message_id}/attachments/{attachment_id}/summary

Required scopes: team_chat:read (GET), team_chat:create (POST). message_id can be a channel message, a thread reply or a direct message, and the attachment must be one of that message's files.

The responses, status codes and rate limits are the same as for the conversation endpoints above. In addition, 404 is returned when you are not a member of the channel or a participant of the direct message, and 422 attachment_not_summarizable when the channel does not offer summaries. Team Chat summaries do not send the attachment.summarized webhook.

Email attachments

Images and PDFs attached to an email a customer sent you can be summarized the same way, at the same price and with the same limits. The email thread endpoints return the summary fields on every entry of attachments:

GET /api/v1/email-integrations/conversations/{conversation_id}/email-thread
GET /api/v1/email-integrations/email-messages/{email_message_id}
GET /api/v1/email-integrations/email-messages/{email_message_id}/thread

Each email attachment has two IDs. Use attachment_id with the summary endpoints above (GET/POST /api/v1/attachments/{attachment_id}/summary), not id: id identifies the email attachment itself (for example for downloads) and returns 404 on the summary endpoints.

{
  "id": "e1a7c9b2-...",
  "attachment_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "contract.pdf",
  "content_type": "application/pdf",
  "file_size": 248112,
  "is_inline": false,
  "ai_summary": null,
  "ai_summary_available": true,
  "ai_summary_credits": 3
}

attachment_id is null for inline images embedded in the email body (is_inline: true, such as signature logos) and may be null for files received before this feature was introduced. These files cannot be summarized: ai_summary is null and ai_summary_available is false.
Files on emails you sent are not offered for summarizing (ai_summary_available: false), the same as outbound chat files.
The attachment.summarized webhook for an email file carries the same attachment_id. Its message_id is the conversation message ID of the email, not the email message id of the thread endpoints.

Webhook

When a summary is ready (from an agent or on demand), SendSeven sends the attachment.summarized webhook event with the attachment, message and conversation IDs and the same summary object. See the Webhook Events Reference.

Attachment fields on messages​

Summary object​

Get a summary​

Request a summary​

Team Chat files​

Email attachments​

Webhook​