Your First Message

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.

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.

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

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

{
  "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.

Check which phone numbers are available in your organization:

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

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

To receive incoming messages, set up a webhook subscription.

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
    }
  }'

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.

Enhance your messages with images, videos, or documents:

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:

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.

Add reactions to messages for engagement tracking:

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

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.

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.

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

• Webhook Events — All available event types
• Contact Management — Manage your address book
• Chat Operations — Group chats, read receipts, typing indicators

• Technical issues — Contact your Linq representative
• Feature requests — Share feedback with your account team
• Integration questions — Consult the V2 Reference for detailed examples

Ready to build? Dive into the V2 Reference to explore all available endpoints and features.