Update an iMessage app card in place

client.messages.updateAppCard(, , ?): MessageUpdateAppCardResponse { chat_id, message }

POST/v3/messages/{messageId}/update

Replaces a previously delivered 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 delivered (409 otherwise — retry after the message.delivered webhook for 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.

ParametersExpand Collapse

messageID: string

formatuuid

body: MessageUpdateAppCardParams { layout, fallback_text, interactive, url }

Visible layout of the card. At least one of caption, subcaption, trailing_caption, trailing_subcaption, or image_url must be set, otherwise the card renders as an empty bubble.

image_url displays a preview image at the top of the card. The image renders on the recipient’s card whether or not they have your app installed. The small icon beside the caption is the app’s own icon and is not settable here.

* Note - requires a trusted chat w/ inbound activity

image_title and image_subtitle render as text overlaid on the image (title bold, subtitle beneath it). They only appear when image_url is set — without an image there is nothing to overlay — so setting either without image_url is rejected.

caption?: string

Primary label, top-left and bold.

maxLength512

image_subtitle?: string

Text shown below image_title, overlaid on the card image. Requires image_url.

maxLength512

image_title?: string

Bold text overlaid on the card image. Requires image_url (rejected without it).

maxLength512

image_url?: string

URL of a JPEG image to display as the card’s preview image; an unreachable or non-image URL returns a validation error. Renders for all recipients regardless of whether they have the app. Note - requires a trusted chat w/ inbound activity.

formaturi

maxLength2048

subcaption?: string

Secondary label, below caption on the left.

maxLength512

trailing_caption?: string

Label shown top-right.

maxLength512

trailing_subcaption?: string

Label shown below trailing_caption, on the right.

maxLength512

fallback_text?: string

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

maxLength1024

interactive?: boolean

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.

url?: string

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

formaturi

maxLength2048

ReturnsExpand Collapse

MessageUpdateAppCardResponse { chat_id, message }

Response for sending a message to a chat

chat_id: string

Unique identifier of the chat this message was sent to

formatuuid

message: SentMessage { id, created_at, delivery_status, 9 more }

A message that was sent (used in CreateChat and SendMessage responses)

id: string

Message identifier (UUID)

formatuuid

created_at: string

When the message was created

formatdate-time

delivery_status: "pending" | "queued" | "sent" | 4 more

Current delivery status of a message

One of the following:

"pending"

"queued"

"sent"

"delivered"

"received"

"read"

"failed"

Deprecatedis_read: boolean

DEPRECATED: Use delivery_status == "read" instead. Whether the message has been read.

parts: Array<TextPartResponse { reactions, type, value, text_decorations } | MediaPartResponse { id, filename, mime_type, 4 more } | LinkPartResponse { reactions, type, value } | IMessageAppPartResponse { app, layout, reactions, 3 more } >

Message parts in order (text, media, and link)

One of the following:

TextPartResponse { reactions, type, value, text_decorations }

A text message part

reactions: Array<Reaction { handle, is_me, type, 2 more } > | null

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 4 more }

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

is_me: boolean

Whether this reaction is from the current user

type: ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:

"love"

"like"

"dislike"

"laugh"

"emphasize"

"question"

"custom"

"sticker"

custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

width?: number

Sticker image width in pixels

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

Character range [start, end) in the value string where the decoration applies. start is inclusive, end is exclusive. Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

MediaPartResponse { id, filename, mime_type, 4 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid

filename: string

Original filename

mime_type: string

MIME type of the file

reactions: Array<Reaction { handle, is_me, type, 2 more } > | null

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 4 more }

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

is_me: boolean

Whether this reaction is from the current user

type: ReactionType

One of the following:

"love"

"like"

"dislike"

"laugh"

"emphasize"

"question"

"custom"

"sticker"

custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

width?: number

Sticker image width in pixels

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

LinkPartResponse { reactions, type, value }

A rich link preview part

reactions: Array<Reaction { handle, is_me, type, 2 more } > | null

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 4 more }

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

is_me: boolean

Whether this reaction is from the current user

type: ReactionType

One of the following:

"love"

"like"

"dislike"

"laugh"

"emphasize"

"question"

"custom"

"sticker"

custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

width?: number

Sticker image width in pixels

type: "link"

Indicates this is a rich link preview part

value: string

The URL

IMessageAppPartResponse { app, layout, reactions, 3 more }

An iMessage app card part.

app: App { bundle_id, name, team_id, app_store_id }

Identifies the iMessage app (Messages app extension) that backs the card.

bundle_id: string

Bundle identifier of the Messages app extension. Must not contain :.

minLength1

maxLength255

Display name of the app, shown by Messages’ fallback UI.

minLength1

maxLength64

team_id: string

The app’s 10-character uppercase alphanumeric team identifier.

app_store_id?: number

The owning app’s App Store id (optional). When set, recipients without the iMessage app installed see a “Get the app” affordance.

formatint64

minimum1

Visible layout of the card. At least one of caption, subcaption, trailing_caption, trailing_subcaption, or image_url must be set, otherwise the card renders as an empty bubble.

* Note - requires a trusted chat w/ inbound activity

caption?: string

Primary label, top-left and bold.

maxLength512

image_subtitle?: string

Text shown below image_title, overlaid on the card image. Requires image_url.

maxLength512

image_title?: string

Bold text overlaid on the card image. Requires image_url (rejected without it).

maxLength512

image_url?: string

formaturi

maxLength2048

subcaption?: string

Secondary label, below caption on the left.

maxLength512

trailing_caption?: string

Label shown top-right.

maxLength512

trailing_subcaption?: string

Label shown below trailing_caption, on the right.

maxLength512

reactions: Array<Reaction { handle, is_me, type, 2 more } > | null

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 4 more }

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

is_me: boolean

Whether this reaction is from the current user

type: ReactionType

One of the following:

"love"

"like"

"dislike"

"laugh"

"emphasize"

"question"

"custom"

"sticker"

custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

width?: number

Sticker image width in pixels

type: "imessage_app"

Indicates this is an iMessage app card part.

url: string

The URL delivered to the iMessage app on tap.

formaturi

fallback_text?: string | null

Fallback text for surfaces that cannot render the card.

sent_at: string | null

When the message was actually sent (null if still queued)

formatdate-time

delivered_at?: string | null

When the message was delivered

formatdate-time

effect?: MessageEffect { name, type } | null

iMessage effect applied to a message (screen or bubble effect)

name?: string

Name of the effect. Common values:

Screen effects: confetti, fireworks, lasers, sparkles, celebration, hearts, love, balloons, happy_birthday, echo, spotlight
Bubble effects: slam, loud, gentle, invisible

type?: "screen" | "bubble"

Type of effect

One of the following:

"screen"

"bubble"

from_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

The sender of this message as a full handle object

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

preferred_service?: ServiceType | null

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

reply_to?: ReplyTo { message_id, part_index } | null

Indicates this message is a threaded reply to another message

message_id: string

The ID of the message to reply to

formatuuid

part_index?: number

The specific message part to reply to (0-based index). Defaults to 0 (first part) if not provided. Use this when replying to a specific part of a multipart message.

formatint32

minimum0

service?: ServiceType | null

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

Update an iMessage app card in place

import LinqAPIV3 from '@linqapp/sdk';

const client = new LinqAPIV3({
  apiKey: process.env['LINQ_API_V3_API_KEY'], // This is the default and can be omitted
});

const response = await client.messages.updateAppCard('69a37c7d-af4f-4b5e-af42-e28e98ce873a', {
  layout: { caption: 'Score: 2 – 1' },
  fallback_text: 'Score update',
  url: 'https://app.example.com/card?game=7f3a&move=2',
});

console.log(response.chat_id);

{
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": {
    "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
    "created_at": "2025-10-23T13:07:55.019-05:00",
    "delivery_status": "pending",
    "is_read": false,
    "parts": [
      {
        "reactions": [
          {
            "handle": {
              "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
              "handle": "+15551234567",
              "joined_at": "2025-05-21T15:30:00.000-05:00",
              "service": "iMessage",
              "is_me": false,
              "left_at": "2019-12-27T18:11:19.117Z",
              "status": "active"
            },
            "is_me": false,
            "type": "love",
            "custom_emoji": null,
            "sticker": {
              "file_name": "sticker.png",
              "height": 420,
              "mime_type": "image/png",
              "url": "https://cdn.linqapp.com/attachments/a1b2c3d4/sticker.png?signature=...",
              "width": 420
            }
          }
        ],
        "type": "text",
        "value": "Hello!",
        "text_decorations": [
          {
            "range": [
              0,
              5
            ],
            "animation": "shake",
            "style": "bold"
          }
        ]
      }
    ],
    "sent_at": null,
    "delivered_at": null,
    "effect": {
      "name": "confetti",
      "type": "screen"
    },
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "handle": "+15551234567",
      "joined_at": "2025-05-21T15:30:00.000-05:00",
      "service": "iMessage",
      "is_me": false,
      "left_at": "2019-12-27T18:11:19.117Z",
      "status": "active"
    },
    "preferred_service": "iMessage",
    "reply_to": {
      "message_id": "550e8400-e29b-41d4-a716-446655440000",
      "part_index": 0
    },
    "service": "iMessage"
  }
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2001/"
  },
  "success": false
}

{
  "error": {
    "status": 409,
    "code": 2013,
    "message": "This chat is unavailable",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2013/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}

Returns Examples

{
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": {
    "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
    "created_at": "2025-10-23T13:07:55.019-05:00",
    "delivery_status": "pending",
    "is_read": false,
    "parts": [
      {
        "reactions": [
          {
            "handle": {
              "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
              "handle": "+15551234567",
              "joined_at": "2025-05-21T15:30:00.000-05:00",
              "service": "iMessage",
              "is_me": false,
              "left_at": "2019-12-27T18:11:19.117Z",
              "status": "active"
            },
            "is_me": false,
            "type": "love",
            "custom_emoji": null,
            "sticker": {
              "file_name": "sticker.png",
              "height": 420,
              "mime_type": "image/png",
              "url": "https://cdn.linqapp.com/attachments/a1b2c3d4/sticker.png?signature=...",
              "width": 420
            }
          }
        ],
        "type": "text",
        "value": "Hello!",
        "text_decorations": [
          {
            "range": [
              0,
              5
            ],
            "animation": "shake",
            "style": "bold"
          }
        ]
      }
    ],
    "sent_at": null,
    "delivered_at": null,
    "effect": {
      "name": "confetti",
      "type": "screen"
    },
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "handle": "+15551234567",
      "joined_at": "2025-05-21T15:30:00.000-05:00",
      "service": "iMessage",
      "is_me": false,
      "left_at": "2019-12-27T18:11:19.117Z",
      "status": "active"
    },
    "preferred_service": "iMessage",
    "reply_to": {
      "message_id": "550e8400-e29b-41d4-a716-446655440000",
      "part_index": 0
    },
    "service": "iMessage"
  }
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2001/"
  },
  "success": false
}

{
  "error": {
    "status": 409,
    "code": 2013,
    "message": "This chat is unavailable",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2013/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}