---
title: Your First Message | API Docs
description: Send your first V2 message and receive webhook notifications in under 5 minutes.
---

Get up and running with the Linq Partner API in under 5 minutes. This guide walks you through sending your first message and receiving webhook notifications.

## Prerequisites

Before you begin, ensure you have:

- A Linq Partner API integration token
- At least one phone number provisioned in your organization
- Basic familiarity with REST APIs and webhooks

**Don’t have an API token yet?** Contact your Linq representative to get started.

## Step 1: Send your first message

Let’s send a simple text message to create a new chat conversation.

### Create a chat and send message

Terminal window

```
curl -X POST https://api.linqapp.com/api/partner/v2/chats \
  -H "X-LINQ-INTEGRATION-TOKEN: your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "send_from": "+19998887777",
    "chat": {
      "phone_numbers": ["+15551234567"]
    },
    "message": {
      "text": "Hello! This is my first message via the Linq API."
    }
  }'
```

**Parameters:**

- `send_from` — Your phone number to send from (must be in your organization)
- `chat.phone_numbers` — Array of recipient phone numbers (include country code)
- `message.text` — The text message to send

### Response

```
{
  "data": {
    "id": 12345,
    "display_name": "+1 (555) 123-4567",
    "service": "iMessage",
    "group": false,
    "chat_handles": [
      {
        "id": 123,
        "phone_number": "+15551234567",
        "service": "iMessage",
        "joined_at": "2025-10-22T10:30:00.000-05:00"
      }
    ],
    "chat_messages": {
      "id": 67890,
      "text": "Hello! This is my first message via the Linq API.",
      "sent_at": "2025-10-22T10:30:00.000-05:00",
      "delivered_at": null,
      "delivery_status": "pending",
      "is_read": false,
      "attachments": []
    }
  }
}
```

You’ve sent your first message. The response includes both the chat and message details.

## Step 2: List your phone numbers

Check which phone numbers are available in your organization:

Terminal window

```
curl https://api.linqapp.com/api/partner/v2/phone_numbers \
  -H "X-LINQ-INTEGRATION-TOKEN: your_token_here"
```

### Response

```
{
  "phone_numbers": [
    {
      "id": 99,
      "phone_number": "+19998887777",
      "forwarding_number": null,
      "response_rate": 75
    }
  ]
}
```

## Step 3: Receive messages with webhooks

To receive incoming messages, set up a webhook subscription.

### Create webhook subscription

Terminal window

```
curl -X POST https://api.linqapp.com/api/partner/v2/webhook_subscriptions \
  -H "X-LINQ-INTEGRATION-TOKEN: your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_subscription": {
      "webhook_url": "https://your-app.com/webhooks/linq",
      "events": ["message.received", "message.sent"],
      "version": 2,
      "active": true
    }
  }'
```

### Webhook payload example

When a message is received, Linq will POST to your webhook URL:

```
{
  "api_version": "v2",
  "created_at": "2025-10-22T10:31:00-06:00",
  "data": {
    "id": "67891",
    "chat_id": "12345",
    "text": "Thanks! This is my reply.",
    "sent_at": "2025-10-22 10:31:00 -0600",
    "is_read": false,
    "from_phone": "+15551234567",
    "service": "iMessage",
    "reaction_id": null,
    "chat_handles": [
      { "identifier": "+15551234567", "display_name": "John Doe", "is_me": false },
      { "identifier": "+19998887777", "display_name": "Your Linq Number", "is_me": true }
    ],
    "attachments": []
  },
  "event_id": "9dabceb9-9194-4dc6-beda-892573f377b4",
  "event_type": "message.received"
}
```

> **Important:** Always validate webhook signatures and implement idempotency to handle duplicate events.

## Step 4: Send a message with attachments

Enhance your messages with images, videos, or documents:

Terminal window

```
curl -X POST https://api.linqapp.com/api/partner/v2/chats/12345/chat_messages \
  -H "X-LINQ-INTEGRATION-TOKEN: your_token_here" \
  -F "message[text]=Check out this image!" \
  -F "message[attachment_urls][]=https://your-cdn.com/image.jpg"
```

To upload files directly instead of referencing URLs, use `message[attachments][]` with `@/path/to/file`:

Terminal window

```
curl -X POST https://api.linqapp.com/api/partner/v2/chats/12345/chat_messages \
  -H "X-LINQ-INTEGRATION-TOKEN: your_token_here" \
  -F "message[text]=Check out these files" \
  -F "message[attachments][]=@/path/to/image.jpg" \
  -F "message[attachments][]=@/path/to/document.pdf"
```

**Supported file types:** Images (JPG, PNG, GIF), videos (MP4, MOV), documents (PDF, DOCX), and more.

## Step 5: React to messages

Add reactions to messages for engagement tracking:

Terminal window

```
curl -X POST https://api.linqapp.com/api/partner/v2/chat_messages/67891/reactions \
  -H "X-LINQ-INTEGRATION-TOKEN: your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "love",
    "operation": "add"
  }'
```

**Available reactions:** `love`, `like`, `dislike`, `laugh`, `emphasize`, `question`

## Phone number formatting

All phone numbers must follow these rules:

- **Format:** `+12223334444` or `2223334444`
- **Country code:** US country code (`+1`) is assumed if not provided
- **Normalization:** Linq automatically normalizes numbers on the backend

Valid: `+15551234567`, `5551234567`. Invalid: `555-123-4567`, `(555) 123-4567`.

## Rate limits

API requests are rate-limited to ensure system stability. If you exceed your limit, you’ll receive a `429 Too Many Requests` response.

Contact your Linq representative to discuss your rate limits or request an increase based on your use case.

## Next steps

Now that you’ve sent your first messages, explore the full API capabilities:

- [**Webhook Events**](/v2/api/operations/tags/webhook-events-documentation/index.md) — All available event types
- [**Contact Management**](/v2/api/operations/tags/contacts/index.md) — Manage your address book
- [**Chat Operations**](/v2/api/operations/tags/chats/index.md) — Group chats, read receipts, typing indicators

## Need help?

- **Technical issues** — Contact your Linq representative
- **Feature requests** — Share feedback with your account team
- **Integration questions** — Consult the [V2 Reference](/v2/api/index.md) for detailed examples

Ready to build? Dive into the [V2 Reference](/v2/api/index.md) to explore all available endpoints and features.