Messages API

  • Article

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:

  1. Register an upload
  2. Upload the attachment
  3. Check status of upload
  4. 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.