Messages

Update an iMessage app card in place

Replaces a previously sent imessage_app card on the recipient's screen with new content, instead of posting a new bubble (like a game move redrawing the board).

The update is delivered as a new message with its own id and delivery lifecycle (message.sent / message.delivered / message.failed webhooks fire for the new id). To update the card again, reference the message id returned by this call.

Constraints:

  • The referenced message must be an imessage_app card sent by you (400 otherwise — inbound cards cannot be updated).
  • The referenced card must already be sent (409 otherwise — retry after its message.sent webhook, in both direct messages and group chats). An update sent the instant that webhook arrives can still get one 409; retry it.
  • The app identity (team_id, bundle_id, name) is inherited from the original card and cannot change; only url, fallback_text, and layout are replaced.
  • iMessage-only, like all app cards.
  • Concurrent updates against the same card are not serialized server-side; the last one delivered wins on the recipient's screen. Serialize updates by always referencing the message id returned by the previous call.
post/v3/messages/{messageId}/update

Request

  • Base URL: https://api.linqapp.com/api/partner
  • URL: https://api.linqapp.com/api/partner/v3/messages/{messageId}/update
  • Auth: HTTP bearer

Path parameters

messageIdstring uuid required
Example:69a37c7d-af4f-4b5e-af42-e28e98ce873a

Id of the app-card message to update (the original card, or the most recent update of it)

Request body

urlstring uri

URL the recipient's app opens when they tap the updated card.

Mutually exclusive with experience and raw_payload_data.

fallback_textstring

Text shown on surfaces that cannot render the card (notifications, lock screen). Defaults to the caption when omitted.

interactiveboolean

Whether the updated card renders as your app's interactive balloon for recipients who have your iMessage app installed. true (default) lets your installed extension draw its live view; false always shows the static layout card. Recipients without your app always see the static card regardless of this flag.

Defaults to true when omitted — it is not inherited from the original card. To keep a card static across updates, re-send interactive: false on each update.

Example request

{
  "app": {
    "name": "Example App",
    "team_id": "A1B2C3D4E5",
    "bundle_id": "com.example.app.MessageExtension",
    "app_store_id": 1234567890
  },
  "url": "https://app.example.com/card?id=abc123",
  "experience": {
    "name": "agentcard",
    "action": "attach_card"
  },
  "fallback_text": "Score update",
  "interactive": true,
  "layout": {
    "caption": "Example App",
    "subcaption": "You said: hello",
    "trailing_caption": "2 min",
    "trailing_subcaption": "expires",
    "image_url": "https://cdn.linqapp.com/example/card-preview.jpg",
    "image_title": "Table for 2",
    "image_subtitle": "Tonight, 7:30 PM"
  }
}

Response

Update accepted — returns the new message version delivering the update

chat_idstring uuid required

Unique identifier of the chat this message was sent to

Example response

{
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": {
    "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
    "service": "iMessage",
    "preferred_service": "iMessage",
    "parts": [
      {
        "type": "text",
        "value": "Hello!"
      }
    ],
    "created_at": "2025-10-23T13:07:55.019-05:00",
    "delivery_status": "pending",
    "effect": {
      "type": "screen",
      "name": "confetti"
    },
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "handle": "+15551234567",
      "service": "iMessage",
      "joined_at": "2025-05-21T15:30:00.000-05:00",
      "line_type": "iMessage"
    },
    "reply_to": {
      "message_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.