---
title: "Start a conversation (InMail, group, company)"
method: POST
path: "/v1/actions/start_conversation"
tags: ["Messages"]
---

# Start a conversation (InMail, group, company)

`POST /v1/actions/start_conversation`

## Request

- Base URL: `https://api.heyreagent.com`
- URL: `https://api.heyreagent.com/v1/actions/start_conversation`
- Auth: HTTP bearer

Start a new conversation: an InMail, a message through Sales Navigator or Recruiter, a group, a company page, a job applicant.

The id must match the product in via: a member id or a profile link for "classic", a Sales Navigator id for "sales_navigator", a Recruiter id for "recruiter".

A company page is written to at its company messaging id (get_company → messaging.id), with companyTopic set; its company id does not work here.

An InMail spends one credit unless the person has an open profile: check get_inmail_credits, and isOpenProfile on get_profile_details.

inmail true is added to the answer when the send was an InMail.

Docs: https://heyreagent.com/docs/actions/start_conversation

## Request body

- object
  - `to` string[], required: Who to write to: LinkedIn profile URLs or member ids. One person, or several for a group conversation. For a company page pass its messaging id.
  - `text` string, required: The first message.
  - `subject` string: Subject line (InMail).
  - `via` 'classic' | 'sales_navigator' | 'recruiter': Which LinkedIn product sends it. sales_navigator and recruiter need that seat on your account.
  - `inmail` boolean: classic only: send as an InMail (to someone you are not connected to).
  - `companyTopic` 'service_request' | 'request_demo' | 'support' | 'careers' | 'other': Required when writing to a company page.
  - `applicantId` string: Required when writing to an applicant of your job posting (from list_job_applicants).
  - `invitationId` string: Required when writing to someone whose invitation you have neither accepted nor declined (from list_received_invitations).
  - `groupId` string: Required when writing to someone through a LinkedIn group you share. A LinkedIn group you share with the person. No action here lists your groups.
  - `recruiter` object: via recruiter only: signature, hiringProjectId (the project to start the conversation in), jobPostingId, sourcingChannel, emailAddress (send by email instead of InMail), visibility (default PRIVATE), inmailIntent, and followUp { subject, text, days 3–28 or weeks 1–4, timezone } to schedule a follow-up (Recruiter PRO).
    - `signature` string
    - `hiringProjectId` string
    - `jobPostingId` string
    - `sourcingChannel` 'JOB_POSTING_RECOMMENDED_MATCHES' | 'JOB_POSTING' | 'REFERRAL' | 'INTERNAL_CANDIDATES' | 'AUTOMATED_SOURCING' | 'RECRUITER_SEARCH' | 'CAREER_SITE'
    - `emailAddress` string, email
    - `visibility` 'PUBLIC' | 'PRIVATE' | 'PROJECT'
    - `inmailIntent` 'HIRE_FOR_CLIENT' | 'HIRE_FOR_OWN_COMPANY'
    - `followUp` object
  - `attachmentUrls` string[]: Files or images to attach. Public https links; each file up to 10 MB, 20 MB in total.
  - `voiceMessageUrl` string, uri: An audio file to send as a voice note (.m4a preferred). A public https link, up to 10 MB.
  - `videoMessageUrl` string, uri: A video file to send as a video note. A public https link, up to 10 MB.
  - `connectionId` string: Which of your LinkedIn accounts to act from (its id from list_linkedin_accounts). Omit to use your first live one.

## Response `200`

It worked. Inside result: sent, chatId, messageId, from, usedToday, dailyLimit.

- Worked
  - `ok` true, required
  - `result` object, required: What was asked for. A field that does not apply is left out, or is null.

## Other responses

- `default`: It did not work. The message says why, in plain English.

---

[API](https://skmtc.dev/heyreagent/apis/heyreagent-api.md) · [All operations](https://skmtc.dev/heyreagent/apis/heyreagent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/heyreagent/apis/heyreagent-api/revisions/917360c5f841?raw)