Skip to main content
POST
Message a Connection
Sends one message to a person. If the account already has a 1:1 conversation with them, the message goes into it. If not, OneShot starts one. Use it after an invitation is accepted, or for a connection the account has never messaged. To answer inside a conversation you already have the id of, use Reply. Paid: flat price per message (see Pricing). Requires the reply grant and an Idempotency-Key header. It shares the reply daily cap and pacing: to LinkedIn, a reply and a message are the same thing.
The human’s account sends the message, and a message LinkedIn accepted cannot be recalled. Every call must carry an Idempotency-Key. The SDKs generate one if you omit it and reuse it on retries, so a retry never sends twice.

Request

string
required
1–255 chars of [A-Za-z0-9_.:-]. A retry with the same key and body replays the accepted response instead of paying and sending again. The key is also stored on the action, so reuse is refused (409 duplicate_request, with the original request_id) even if the cache is unavailable.
string
required
Connected LinkedIn account id.
string
required
The connection. Takes what Invite takes: an HTTPS linkedin.com/in/ profile URL, a slug or a provider id.
string
required
1–4000 characters.

Before payment

Each of these returns a non-2xx and is never settled: Whether the person is a connection is checked at send time, not here. See Outcome.

Response

Outcome

Poll GET /v1/requests/{request_id} (the SDK waits for you):
  • completed: { "action_request_id", "status": "sent", "conversation_id", "message_id", "provider_message_id", "sent_at" }. conversation_id is the 1:1 conversation the message went into, whether it existed or was just created. It then appears in Conversations and Messages, and you can keep the thread going with Reply.
  • failed, with an error_code. Two of them mean “defer”, not “give up”:
    • not_connected: the person is not a first-degree connection of the account. Send an invitation and try again once it is accepted.
    • rate_limited: LinkedIn throttled the account. Retry later with a new key.
    The others: target_not_found (no profile matches), grant_revoked, account_disconnected, content_rejected, account_send_limit. The failed-job sweep refunds messages that failed before sending.
  • processing with send_status: "ambiguous": the upstream timed out after the request may have been delivered. OneShot does not retry blindly. It looks for the message in the chat every few minutes, re-attempts once if there is still no trace after 10 minutes, and after 24 hours without confirmation fails the job with send_unverified.

Example