Messages API
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.
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
, andattachments
. The member must be able to edit the content of thesubject
, thebody
, and theattachments
, 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.
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:
|
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. |
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.
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"
]
}
HTTP/2 201
x-linkedin-id: {thread=urn:li:messagingThread:123ABC, id=123456789}
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.
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",
}
HTTP/2 201
x-linkedin-id: {id=1-MTU3ODUzNjc5MjYxOWIxOTM2NC0wMDEmYTI3YjEwM2YtMmI1MC00YjM0LTk0NzEtYWU4MDE4ZTkzNDE0XzAwNA%3D%3D%2C+thread%3Durn%3Ali%3AmessagingThread%3A2-YTI3YjEwM2YtMmI1MC00YjM0LTk0NzEtYWU4MDE4ZTkzNDE0XzAwNA%3D%3D%7D
Refer here for the message schema used in Compliance Events API.
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:
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.
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"
}
]
}
}
{
"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)",
}
}
Use the uploadUrl
from the previous step to upload the attachment.
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"
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"
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.
GET https://api.linkedin.com/v2/assets/C5400AQHpR1ANqMWqNA
{
"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"
}
Use the created DigitalMediaAsset URN returned in the response's field asset
to create a message with the attachment.