Create a new chat
client.chats.create(ChatCreateParams { from, message, to } body, RequestOptionsoptions?): ChatCreateResponse { chat }
POST/v3/chats
Create a new chat with specified participants and send an initial message. The initial message is required when creating a chat.
Message Effects
You can add iMessage effects to make your messages more expressive. Effects are optional and can be either screen effects (full-screen animations) or bubble effects (message bubble animations).
Screen Effects: confetti, fireworks, lasers, sparkles, celebration,
hearts, love, balloons, happy_birthday, echo, spotlight
Bubble Effects: slam, loud, gentle, invisible
Only one effect type can be applied per message.
Inline Text Decorations (iMessage only)
Use the text_decorations array on a text part to apply styling and animations to character ranges.
Each decoration specifies a range: [start, end) and exactly one of style or animation.
Styles: bold, italic, strikethrough, underline
Animations: big, small, shake, nod, explode, ripple, bloom, jitter
{
"type": "text",
"value": "Hello world",
"text_decorations": [
{ "range": [0, 5], "style": "bold" },
{ "range": [6, 11], "animation": "shake" }
]
}Note: Style ranges (bold, italic, etc.) may overlap, but animation ranges must not overlap with other animations or styles. Text decorations only render for iMessage recipients. For SMS/RCS, text decorations are not applied.
First-Message Link Restriction
To protect sender deliverability, the first outbound message of a new chat cannot be a link.
The request is rejected with 400 (error code 1005) when:
- The message contains a
linkpart (explicit rich-preview link), or - Any
textpart contains a URL.
This rule applies only to POST /v3/chats. Follow-up messages on an existing chat
(POST /v3/chats/{chatId}/messages) are not subject to this restriction.
Create a new chat
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 chat = await client.chats.create({
from: '+12052535597',
message: { parts: [{ type: 'text', value: 'Hello! How can I help you today?' }] },
to: ['+12052532136'],
});
console.log(chat.chat);{
"chat": {
"id": "94c6bf33-31d9-40e3-a0e9-f94250ecedb9",
"display_name": "+14155551234, +14155559876",
"handles": [
{
"id": "550e8400-e29b-41d4-a716-446655440010",
"handle": "+14155551234",
"joined_at": "2025-05-21T15:30:00.000Z",
"service": "iMessage",
"is_me": true,
"left_at": "2019-12-27T18:11:19.117Z",
"status": "active"
},
{
"id": "550e8400-e29b-41d4-a716-446655440011",
"handle": "+14155559876",
"joined_at": "2025-05-21T15:30:00.000Z",
"service": "iMessage",
"is_me": false,
"left_at": "2019-12-27T18:11:19.117Z",
"status": "active"
}
],
"is_group": false,
"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"
},
"service": "iMessage",
"health_score": {
"reason": "Not enough engagement",
"score": 35,
"updated_at": "2026-05-01T18:28:25Z"
}
}
}{
"error": {
"status": 400,
"code": 1002,
"message": "Phone number must be in E.164 format"
},
"success": false
}{
"error": {
"status": 401,
"code": 2004,
"message": "Unauthorized - missing or invalid authentication token"
},
"success": false
}{
"error": {
"status": 500,
"code": 3006,
"message": "Internal server error"
},
"success": false
}Returns Examples
{
"chat": {
"id": "94c6bf33-31d9-40e3-a0e9-f94250ecedb9",
"display_name": "+14155551234, +14155559876",
"handles": [
{
"id": "550e8400-e29b-41d4-a716-446655440010",
"handle": "+14155551234",
"joined_at": "2025-05-21T15:30:00.000Z",
"service": "iMessage",
"is_me": true,
"left_at": "2019-12-27T18:11:19.117Z",
"status": "active"
},
{
"id": "550e8400-e29b-41d4-a716-446655440011",
"handle": "+14155559876",
"joined_at": "2025-05-21T15:30:00.000Z",
"service": "iMessage",
"is_me": false,
"left_at": "2019-12-27T18:11:19.117Z",
"status": "active"
}
],
"is_group": false,
"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"
},
"service": "iMessage",
"health_score": {
"reason": "Not enough engagement",
"score": 35,
"updated_at": "2026-05-01T18:28:25Z"
}
}
}{
"error": {
"status": 400,
"code": 1002,
"message": "Phone number must be in E.164 format"
},
"success": false
}{
"error": {
"status": 401,
"code": 2004,
"message": "Unauthorized - missing or invalid authentication token"
},
"success": false
}{
"error": {
"status": 500,
"code": 3006,
"message": "Internal server error"
},
"success": false
}