Create and Manage Conversation Ads (Legacy)

  • Article

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

Important

The Conversation Ads API replaces the sponsoredConversations API for creating Sponsored Conversation entities and Sponsored Message Content.

A Conversation Ad is a LinkedIn ad format that enables advertisers to deliver planned automated messages to a targeted LinkedIn member's inbox. It provides a chat-like experience between both the member and the advertiser.

Within the LinkedIn API, Conversation Ads are represented by the Sponsored Conversation entity. Sponsored Conversations are composed of Sponsored Message Content.

Refer to the Conversation Ads Use Case Guide for API workflows. You can also refer to Conversation Ads Overview for an ad format overview.

Permissions

Permission Description
rw_ads Manage and read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
    		•
    r_ads Read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
  • VIEWER
    		•

    See Account Access Controls for more information on ad account roles.

    A sponsored conversation is represented by a graph that contains sponsored message content nodes which are triggered by user button clicks that are mapped to the nodes. When the user clicks a button, the button responds with content that resides in a specific location on the graph mapped to the button.

    Conversation Ads require an advertiser to design the graph per their specification and objectives through mapping the buttons to the sponsored message content nodes on the graph.

    The following sections provide information about how to design both the sponsored conversation and the sponsored message content.

    This section explains how to manage sponsored ad conversations.

    SponsoredConversation Schema

    Field Type Description
    id long, read-only ID key for the current conversation
    firstMessageContent Sponsored Message Content URN Root of the sponsored conversation graph. From this node, you can traverse all the messages in the conversation. Cannot be specified on creation.
    parentAccount Sponsored Account URN, create-only ID of the parent Sponsored Account that created the current conversation
    editable boolean Indicates whether the current sponsored conversation and child content can be edited. Starting July 2021 this field will be automatically set to false when the SponsoredConversation is set as the subContent of an AdInMailContent entity.

    Create a Conversation

    A conversation stores the entry of a message tree. You can create a conversation by calling the sponsoredConversations endpoint.

    Sample Request

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

    {
   "parentAccount": "urn:li:sponsoredAccount:123456"
}

    Validations:

    • The specified parentAccount must exist and be valid
    • The user must have the permission to manage the account
    • You cannot set the firstMessageContent when initially creating a sponsoredConversation. It can only be set by a subsequent partial update call.

    Successful response will have Status 201 Created and the ID in the x-linkedin-id response header.

    Get a Conversation

    A conversation stores a message tree entry. You can retrieve it by calling the sponsoredConversations endpoint.

    GET https://api.linkedin.com/v2/sponsoredConversations/{sponsoredConversationId}

    Sample Request

    GET https://api.linkedin.com/v2/sponsoredConversations/1234

    Sample Response

    {
    "firstMessageContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,5678)",
    "editable": true,
    "id": 2620,
    "parentAccount": "urn:li:sponsoredAccount:518374847",
    "$URN": "urn:li:sponsoredConversation:2620"
}

    Get a Conversation in Batch

    You can retrieve multiple conversations at the same time retrieve it by calling the sponsoredConversations endpoint.

    GET https://api.linkedin.com/v2/sponsoredConversations?ids=List({sponsoredConversationId})

    Sample Request

    GET https://api.linkedin.com/v2/sponsoredConversations?ids=List(1234)

    Sample Response

    {
    "statuses":{
        "1234":200
    },
    "results":{
        "1234":{
            "id":1234,
            "parentAccount":"urn:li:sponsoredAccount:12345",
            "editable":true,
            "firstMessageContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,5678)"
        }
    },
    "errors":{}
}

    Partially Updating a Conversation

    After creating a conversation, you can also partially update it.

    POST https://api.linkedin.com/v2/sponsoredConversations/{sponsoredConversationId}

    Sample Request

    POST https://api.linkedin.com/v2/sponsoredConversations/1234

    {
  "patch": {
    "$set": {
      "firstMessageContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,5678)"
    }
  }
}

    Validations:

    • The user must have the permission to manage the account
    • The sponsoredConversation must be editable
    • The firstMessageContent must be valid and this sponsoredMessageContent must created under the same sponsoredConversation.

    The content in this section explains how to manage sponsored message content.

    SponsoredMessageContent Schema

    Field Type Description
    id long, read-only ID key for the current conversation content
    type String, read-only
  • INFORMATION. If the nextAction field is null or a SponsoredContentUrn. The goal is to provide information to the recipient.
  • OPTION_PROVIDING. If the nextAction is an array. The goal is to give the options/form/landing page for members to click on.
    		•
    nextAction SponsoredMessageContentUrn or SponsoredMessageOption[] Indicates whether the succeeding action is an array of options or the direct next message in the thread.
    bodySource String, AdFormUrn or SponsoredMessageAttachmentWithText
  • The body of the message.
  • AdFormUrn: The URN for this creative's lead generation form, body message should be the same with a Thank You message on the form. The body will be populated in frontend at runtime.
  • SponsoredMessageAttachmentWithText. The attachment with a text as the body of the message. The attachment is a vector image that appears after the text.
    		•
    sponsoredConversation SponsoredConversationUrn Read-only URN of the parent sponsoredConversation for this SponsoredMessageContent.

    SponsoredMessageOption Schema

    Field Type Description
    type SponsoredMessageReplyType Type of the reply
    nextContext com.linkedin.common.SponsoredMessageContentUrn URN of the next message content to show.
    optionText string The text of the content shown on the button.
    actionTarget AdFormUrn or URL Specify AdFormUtn for LEAD_GENERATION or LEAD_GENERATION_THANK_YOU options. Or specify a landing page URL for the WEBSITE_VISIT option.

    Validations

    The following invariants must hold when creating/updating/deleting SponsoredMessageContent, otherwise it will throw validation errors (4xx error code).

    All SponsoredMessageContents within a conversation has the following tree level checks:

    • The maximum number of SponsoredMessageContents within a conversation is 25
    • All SponsoredMessageContentUrn references must exist
    • Cyclical references between the message nodes are not allowed

    Individual SponsoredMessageContent Checks:

    • If the bodySource is a leadGenerationForm:
      • The message type must be OPTION_PROVIDING
      • It must have at least one LEAD_GENERATION_THANK_YOU SponsoredMessageOption
      • The leadGenerationForm account needs to match the Conversation parentAccount
    • If the bodySource is text:
      • The text length must be less than or equal to 500 characters
    • If the bodySource is AttachmentAndText:
      • The text length must be less than or equal to 500 characters
      • The image must be an digitalmediaAssetUrn
    • A SponsoredMessageContent is defined to be an INFORMATION type if:
      • The nextAction must be null or be a SponsoredMessageContentUrn
      • If the nextAction is a SponsoredMessageContentUrn, the nextAction must not point to a SponsoredMessageContent with a leadGenerationForm bodySource
    • A SponsoredMessageContent is defined to be an OPTION_PROVIDING type if:
      • The nextAction must be an array
      • The array must have at least 1 SponsoredMessageOption but no more than 5 SponsoredMessageOptions

    SponsoredMessageOption Validations:

    • optionText must be between 1 and 35 characters
    • If the type of the option is LEAD_GENERATION:
      • The actionTarget must be a leadGenerationForm
      • The nextAction field must not be null
      • The nextAction field is required to point to a SponsoredMessageContent with a bodySource of type leadGenerationForm (to get thank you message from adForms endpoint and show on clients), this urn must be the same as AdFormUrn in this option's actionTarget
      • The SponsoredMessageContent should be OPTION_PROVIDING (i.e.: nextAction must be an array and the array must have between 1 to 5 SponsoredMessageOptions).
    • If the type of the option is LEAD_GENERATION_THANK_YOU:
      • The actionTarget must be a leadGenerationForm
      • The bodySource of this SponsoredMessageContent must be leadGenerationForm and the AdFormUrn must be the same as in this option's actionTarget
      • The SponsoredMessageContent should be OPTION_PROVIDING (i.e.: nextAction must be an array and the array must have between 1 to 5 SponsoredMessageOptions).
      • Note that the optionText will always be set to the thank you message from the ad form regardless of the input provided for the SponsoredMessageOption optionText.
    • If the type of the option is EXTERNAL_WEBSITE:
      • The actionTarget must be a landingPage
      • The nextAction must not point to a SponsoredMessageContent with a bodySource of type leadGenerationForm
    • If the type of the option is SIMPLE_REPLY:
      • The actionTarget must be null
      • The nextAction must exist
      • The nextAction must not point to a SponsoredMessageContent with a bodySource of type leadGenerationForm
    • If the type of the option is UNKNOWN:
      • This is always invalid

    Create Sponsored Message Content

    Sponsored message content refers to conversation message nodes that can be sent to dedicated audiences that have established communications with your company. The nodes contain preset text responses that are triggered by user replies depending on the reply topic. You can create message nodes in your conversation by calling the sponsoredMessageContents endpoint.

    Depending on the content nodes in your conversation, the first content created through the API must be a content entity without a next action such as the final message in the conversation.

    POST https://api.linkedin.com/v2/sponsoredConversations/{sponsoredConversationId}/sponsoredMessageContents

    Sample Request (without next actions)

    POST https://api.linkedin.com/v2/sponsoredConversations/1234/sponsoredMessageContents

    {
  "bodySource": {
    "text": "Thank you for your time!"
  }
}

    Sample Request (with next actions)

    POST https://api.linkedin.com/v2/sponsoredConversations/1234/sponsoredMessageContents

    {
  "bodySource": {
    "text": "Hello!"
  },
  "nextAction": {
    "array": [
      {
        "optionText": "No thanks",
        "type": "SIMPLE_REPLY",
        "nextContent" : "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,5678)"
      },
      {
        "optionText": "Go to website",
        "type": "EXTERNAL_WEBSITE",
        "nextContent" : "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,5678)",
        "actionTarget": { "landingPage": "https://www.example.com" }
      }
    ]
  }
}

    Sample Request SponsoredMessageAttachmentWithText

    The attachment asset is created using urn:li:digitalmediaRecipe:ads-image. See note in Assets API for more info.

    POST https://api.linkedin.com/v2/sponsoredConversations/1234/sponsoredMessageContents

    {
  "bodySource": {
    "attachmentAndText": {
      "attachment": {
        "messageAttachment": {
          "image": "urn:li:digitalmediaAsset:C5F0CAQGAq0elyqCQGQ"
        }
      },
      "text": "Hello"
    }
  }
}

    Create Sponsored Message Content in Batch

    Sponsored message content refers to conversation message nodes that can be sent to dedicated audiences which have established communications with your company. The nodes contain preset text responses that are triggered by specific user replies depending on the reply topic. You can create message nodes in your conversation by calling the sponsoredMessageContents endpoint.

    Sample Request

    POST https://api.linkedin.com/v2/sponsoredConversations/1234/sponsoredMessageContents

    {
  "elements": [
    {
        "bodySource": {"text": "Test message"},
        "nextAction": {"string": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,5678)"}
    },
    {
        "bodySource": {"text": "Another message"}
    },
    {
        "bodySource": {"text": "Another message with simple reply"},
        "nextAction": {"array": [{"optionText": "Simple Reply", "type": "SIMPLE_REPLY"}]}
    }
  ]
}

    Get All Sponsored Message Contents

    You can retrieve message node contents in a created conversation by calling the sponsoredMessageContents endpoint.

    GET https://api.linkedin.com/v2/sponsoredConversations/{sponsoredConversationId}/sponsoredMessageContents

    Sample Request

    GET https://api.linkedin.com/v2/sponsoredConversations/1234/sponsoredMessageContents

    Sample Response

    { 
   "elements":[ 
      { 
         "sponsoredConversation":"urn:li:sponsoredConversation:1234",
         "id":5678,
         "bodySource":{ 
            "text":"thank you!"
         },
         "body":"thank you!",
         "type":"INFORMATION",
         "$URN":"urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,5678)"
      },
      { 
         "sponsoredConversation":"urn:li:sponsoredConversation:1234",
         "id":6789,
         "bodySource":{ 
            "text":"test intro"
         },
         "nextAction":{ 
            "array":[ 
               { 
                  "landingPage":"http://linkedin.com",
                  "actionTarget":{ 
                     "landingPage":"http://linkedin.com"
                  },
                  "type":"EXTERNAL_WEBSITE",
                  "nextContent":"urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,6789)",
                  "optionText":"first button"
               }
            ]
         },
         "body":"test intro",
         "type":"OPTION_PROVIDING",
         "$URN":"urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,7478)"
      },
      { 
         "sponsoredConversation":"urn:li:sponsoredConversation:1234",
         "id":7486,
         "bodySource":{ 
            "text":"can you see the whole ads"
         },
         "nextAction":{ 
            "array":[ 
               { 
                  "type":"SIMPLE_REPLY",
                  "nextContent":"urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,7494)",
                  "optionText":"yes"
               }
            ]
         },
         "body":"can you see the whole ads",
         "type":"OPTION_PROVIDING",
         "$URN":"urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,7486)"
      }
   ],
   "paging":{ 
      "count":10,
      "start":0,
      "links":[ 

      ]
   }
}

    Get Single Sponsored Message Contents

    You can retrieve specific message node content in a created conversation by calling the sponsoredMessageContents endpoint.

    GET https://api.linkedin.com/v2/sponsoredConversations/{sponsoredConversationId}/sponsoredMessageContents/{sponsoredMessageContentId}

    Sample Request

    GET https://api.linkedin.com/v2/sponsoredConversations/1234/sponsoredMessageContents/7494

    Sample Response

    { 
    "sponsoredConversation":"urn:li:sponsoredConversation:1234",
    "id":7478,
    "bodySource":{
        "text":"test intro"
    },
    "nextAction":{
      "array":[
        {
        "landingPage":"http://example.com",
        "actionTarget":{
            "landingPage":"http://example.com"
        },
        "type":"EXTERNAL_WEBSITE",
        "nextContent":"urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,7486)",
        "optionText":"first button"
        }
      ]
    },
    "body":"test intro",
    "type":"OPTION_PROVIDING"
}

    Partially Update Sponsored Message Content

    You can partially update existing sponsored message content.

    POST https://api.linkedin.com/v2/sponsoredConversations/{sponsoredConversationId}/sponsoredMessageContents/{sponsoredMessageContentId}

    Sample Request

    POST https://api.linkedin.com/v2/sponsoredConversations/1234/sponsoredMessageContents/5678

    {
    "patch": {
        "$set": {
            "bodySource":{  
                 "leadGenerationForm":"urn:li:adForm:777890"
            },
            "nextAction":{  
                  "array":[  
                    {
                            "actionTarget": {
                            "landingPage": "https://abc.xyz/get/?mcv=123"
                        },
                        "type": "EXTERNAL_WEBSITE",
                        "nextContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1234,5678)",
                        "optionText": "Visit website"
                    }
                  ]
               }
        }
    }
}

    A successful response returns a 204 No Content HTTP status code and the ID in the x-linkedin-id response header.

    Partial Update of Sponsored Message Contents in Batch Mode

    You can also partially update sponsored message contents in batch mode. You must update in batch mode when creating message contents containing the leadGenForm.

    POST https://api.linkedin.com/v2/sponsoredConversations/{sponsoredConversationId}/sponsoredMessageContents?ids=List({sponsoredMessageContentIds})

    Sample Request

    POST https://api.linkedin.com/v2/sponsoredConversations/987/sponsoredMessageContents?ids=List(123,345)

    {  
   "entities":{  
      "3146":{  
         "patch":{  
            "$set":{  
               "nextAction":{  
                  "array":[  
                     {
                        "type": "SIMPLE_REPLY",
                        "nextContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1810,3122)",
                        "optionText": "View program details"
                    },
                    {
                        "type": "LEAD_GENERATION",
                        "actionTarget":{  
                           "leadGenerationForm":"urn:li:adForm:778243"
                        },
                        "nextContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1810,3130)",
                        "optionText": "Speak with admissions"
                    },
                    {
                        "type": "SIMPLE_REPLY",
                        "nextContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1810,3138)",
                        "optionText": "No thanks"
                    }
                  ]
               }
            }
         }
      },
      "3122":{  
         "patch":{  
            "$set":{  
               "nextAction":{  
                  "array":[  
                     {
                        "actionTarget": {
                            "landingPage": "https://abc.com/get/?mcv=JDG550"
                        },
                        "type": "EXTERNAL_WEBSITE",
                        "nextContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1810,3106)",
                        "optionText": "Visit website"
                    },
                    {
                        "type": "LEAD_GENERATION",
                        "actionTarget":{  
                           "leadGenerationForm":"urn:li:adForm:778243"
                        },
                        "nextContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:1810,3114)",
                        "optionText": "Speak with admissions"
                    }
                  ]
               }
            }
         }
      },
      "3114":{  
         "patch":{  
            "$set":{  
               "bodySource":{  
                  "leadGenerationForm":"urn:li:adForm:778243"
               },
               "nextAction":{  
                  "array":[  
                     {  
                        "type":"LEAD_GENERATION_THANK_YOU",
                        "actionTarget":{  
                           "leadGenerationForm":"urn:li:adForm:778243"
                        },
                        "optionText":"Learn more"
                     }
                  ]
               }
            }
         }
      },
      "3130":{  
         "patch":{  
            "$set":{  
               "bodySource":{  
                  "leadGenerationForm":"urn:li:adForm:778243"
               },
               "nextAction":{  
                  "array":[  
                     {  
                        "type":"LEAD_GENERATION_THANK_YOU",
                        "actionTarget":{  
                           "leadGenerationForm":"urn:li:adForm:778243"
                        },
                        "optionText":"Learn more"
                     }
                  ]
               }
            }
         }
      }
   }
}

    Deleting Multiple Sponsored Message Content

    You can delete multiple instances of Sponsored Message Content.

    DELETE https://api.linkedin.com/v2/sponsoredConversations/{sponsoredConversationId}/sponsoredMessageContents?ids=List({sponsoredMessageContentIds})

    Sample Request

    DELETE https://api.linkedin.com/v2/sponsoredConversations/678/sponsoredMessageContents?ids=List(123,234)

    Sample Response

    { 
   "results":{
      "7613":{
         "status":204
      },
      "7605":{
         "status":204
      }
   },
   "errors":{

   }
}

    Create AdInMail Content for a Conversation Ad

    InMail ads provide a way for marketers to increase their LinkedIn reach by sending personalized messages to their targeted audiences. AdInMail are tailored InMail messages that are delivered to a LinkedIn member's InMail inbox.

    You can call the adInMailContentsV2 endpoint to create an AdInMailContents object to use in an ad creative. For Conversation Ads you need to provide a AdInMailGuidedRepliesSubContent as the subContent.

    Sample Request

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

    {
    "account": "urn:li:sponsoredAccount:51234",
    "name": "Employer Branding Journey",
    "htmlBody": "<p>123<br><br>456</p>",
    "subContent": {
        "com.linkedin.ads.AdInMailGuidedRepliesSubContent": {
            "sponsoredConversation": "urn:li:sponsoredConversation:508"
        }
    }, 
    "legalText": {}, 
    "subject": "Example Conversation Ad Content",
    "sender": {
        "displayName": "John Doe", 
        "displayPictureV2": "urn:li:digitalmediaAsset:C5ABC123", 
        "from": "urn:li:person:abc"
    }
}