Messages API

Article
05/08/2023

Note

Usage of this API is restricted to approved partners, subject to limitations via API agreement.

LinkedIn offers the Messages API allowing members to create messages to one or more first-degree connections or reply to existing conversations. The Compliance Events API provides options to monitor a given member's messaging activities.

Requirements

You must adhere to the following requirements when posting a message to LinkedIn:

A message must be associated with a specific member action. Member actions do not include an automated or scheduled event. For example, a member navigating through your application is not a specific member action.
Members must opt in to sending a message, as opposed to opting out of sending a message. The member must be given a choice about whether to send the message or not.
If you choose to present the member with a pre-prepared message, you must provide the member with a proposed draft of the pre-prepared message, including the subject, body, and attachments. The member must be able to edit the content of the subject, the body, and the attachments, and the member must take an affirmative action to send the message after you present the member with the draft.
A message must be posted at, or around the time the member took action to send the message.
An application must not offer any direct or indirect incentive to the member as a reward for issuing a message.
An application must not offer any direct or indirect incentive to the recipients of a message.
Messages posted on LinkedIn must not contain any HTML.

Schema

Field Name	Format	Description
id	String	The entity ID of the message. Read only.
recipients	Person URN[]	Recipients of the conversation message. Optional. Required if `thread` is missing and must be omitted if `thread` is present.
subject	String	The subject of the conversation. Also known as the thread conversation's name. Optional.
body	String	The content of the message.
messageType	enum String	The message type. Can be the following enums: MEMBER_TO_MEMBER - Member to member message.
thread	MessagingThread URN	The MessagingThread URN that ties this message to other related messages. A message can only belong to one thread. Optional. Required if `recipients` is missing and must be omitted if `recipients` is present.
attachments	URN[]	The list of attachments for this message. This field contains a list of encrypted URNs representing files stored outside of the messaging system. It is currently a DigitalMediaAsset URN. Defaults to empty.

Create a New Message

To create a new message, recipients field is required to specify who to send the new message to. Once the message is created, the thread value will be generated in the response. This will be used for future messages in the same conversation.

Sample New Message Request

POST https://api.linkedin.com/v2/messages

{
  "recipients": [
    "urn:li:person:123ABC",
    "urn:li:person:456DEF"
  ],
  "subject": "Group conversation title",
  "body": "Hello everyone! This is a message conversation to demo the Message API.",
  "messageType": "MEMBER_TO_MEMBER",
  "attachments": [
    "urn:li:digitalMediaAsset:123ABC"
  ]
}

Sample New Message Header Response

HTTP/2 201

x-linkedin-id: {thread=urn:li:messagingThread:123ABC, id=123456789}

Reply to an Existing Conversation

To reply to an existing conversation, supply either the list of PersonUrns in recipients or the threadUrn in thread. If both are present, the request will be rejected.

Sample Reply Request

POST https://api.linkedin.com/v2/messages

{
  "body": "Replying back to the above new message. I love APIs!",
  "messageType": "MEMBER_TO_MEMBER",
  "thread": "urn:li:messagingThread:123ABC",
}

Sample Reply Header Response

HTTP/2 201

x-linkedin-id: {id=1-MTU3ODUzNjc5MjYxOWIxOTM2NC0wMDEmYTI3YjEwM2YtMmI1MC00YjM0LTk0NzEtYWU4MDE4ZTkzNDE0XzAwNA%3D%3D%2C+thread%3Durn%3Ali%3AmessagingThread%3A2-YTI3YjEwM2YtMmI1MC00YjM0LTk0NzEtYWU4MDE4ZTkzNDE0XzAwNA%3D%3D%7D

Messaging Activities on Compliance Events API

Refer here for the message schema used in Compliance Events API.

Message Attachment Creation

To create a message attachment, utilize the Assets API to upload the media. The following steps outlines how to create a message with an attachment:

Register an upload
Upload the attachment
Check status of upload
Create an Attachment Message

Register an Upload

Use the registerUpload action to register the attachment upload. Use the HTTP URL returned to upload the attachment. Use the uploadUrl returned within the response body to upload your image. You will need to supply the recipe: urn:li:digitalmediaRecipe:ads-image. See note in Assets API for more details.

Register Request

POST https://api.linkedin.com/v2/assets?action=registerUpload

Make sure you set the Content-Type header to application/json.

{
    "registerUploadRequest": {
        "owner": "urn:li:person:123ABC",
        "recipes": [
            "urn:li:digitalmediaRecipe:messaging-attachment"
        ],
        "serviceRelationships": [
            {
                "identifier": "urn:li:userGeneratedContent",
                "relationshipType": "OWNER"
            }
        ]
    }
}

Register Response

{
    "value": {
        "uploadMechanism": {
            "com.linkedin.digitalmedia.uploading.MediaUploadHttpRequest": {
                "headers": {
                    "media-type-family": "STILLIMAGE"
                },
                "uploadUrl": "https://api.linkedin.com/mediaUpload/C5522AQHn46pwH96hxQ/feedshare-uploadedImage/0?ca=vector_feedshare&cn=uploads&m=AQLKRJOn_yNw6wAAAW2T0DWnRStny4dzsNVJjlF3aN4-H3ZR9Div77kKoQ&app=1983914&sync=0&v=beta&ut=1Dnjy796bpjEY1"
            }
        },
       "mediaArtifact": "urn:li:digitalmediaMediaArtifact:(urn:li:digitalmediaAsset:C5522AQHn46pwH96hxQ,urn:li:digitalmediaMediaArtifactClass:ads-image)",
    }
}

Upload the Attachment

Use the uploadUrl from the previous step to upload the attachment.

Upload Request

curl -i --upload-file ~/Desktop/MyAttachment.jpg -H 'Authorization: Bearer Redacted' "https://api.linkedin.com/mediaUpload/C5522AQHn46pwH96hxQ/feedshare-uploadedImage/0?ca=vector_feedshare&cn=uploads&m=AQLKRJOn_yNw6wAAAW2T0DWnRStny4dzsNVJjlF3aN4-H3ZR9Div77kKoQ&app=1983914&sync=0&v=beta&ut=1Dnjy796bpjEY1"

Upload Response

HTTP/2 201 
server: Play
set-cookie: lang=v=2&lang=en-us; Path=/; Domain=api.linkedin.com
date: Wed, 16 Oct 2019 06:25:12 GMT
content-length: 0
x-li-proto: http/2
report-to: {"group":"network-errors","max_age":2592000,"endpoints":[{"url":"https://www.linkedin.com/li/rep"}],"include_subdomains":true}
nel: {"report_to":"network-errors","max_age":1296000,"success_fraction":0.0001,"failure_fraction":1,"include_subdomains":true}
x-li-uuid: slguD4sMzhUwATrTkisAAA==
set-cookie: lidc="b=ETB86:g=301:u=12:i=1571207079:t=1571261189:s=AQGEngFr_Vc-bGAR4gREsIou-eLZon31"

Check the Status of Upload

You can retrieve asset information using the Asset ID from the digitalmediaAsset URN. Depending on content size, it might take a few minutes for the upload to complete.

Status Request

GET https://api.linkedin.com/v2/assets/C5400AQHpR1ANqMWqNA

Status Response

{
    "created": 1521582700662,
    "id": "C5405AQEOFHXqeM2vRA",
    "lastModified": 1521583180818,
    "mediaTypeFamily": "VIDEO",
    "recipes": [
        {
            "recipe": "urn:li:digitalmediaRecipe:messaging-attachment",
            "status": "PROCESSING"
        }
    ],
    "serviceRelationships": [
        {
            "identifier": "urn:li:userGeneratedContent",
            "relationshipType": "OWNER"
        }
    ],
    "status": "ALLOWED"
}

Create an Attachment Message

Use the created DigitalMediaAsset URN returned in the response's field asset to create a message with the attachment.

Partager via