Share via

Conversation Ads API

  • Article

Warning

Deprecation Notice
The Marketing Version 202310 (Marketing October 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will 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.

Linkedin is introducing its next generation of APIs to create and manage Conversation Ads, enabling advertisers to better deliver automated messages to a targeted LinkedIn member's inbox. This API replaces the previous /sponsoredConversations API.

Permissions

Permission Description
rw_ads Manage and read an authenticated member's Ad Accounts. In addition, authenticated member must have READ access for a Company Page. Have one of the following Ad Account roles:
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
    		•
    r_ads Read an authenticated member's Ad Account. 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.

    Workflow

    1. Create a SponsoredConversation.
    2. If you are using attachments in a conversation, upload SponsoredMessageContent Asset.
    3. Create a tree of SponsoredMessageContent to represent a conversation.
    4. Update SponsoredConversation with reference to first SponsoredMessageContent.
    5. Create an AdInMailContent using GuidedReplies as sub-content by using the Urn of the completed Sponsored Conversation.
    6. Create a DRAFT conversation ad creative with the adInMailContent URN returned in the previous step as its content reference. See Create and Manage Creatives.
    7. Test the DRAFT conversation ad.
    8. Make any necessary modifications based on testing.

      Note

      The creative should be in DRAFT status.

    9. Activate the creative by updating the creative status to ACTIVE.

      Note

      The creative will be directed to the review queue after activation.

    This section explains how to manage sponsored ad conversations.

    SponsoredConversation Schema

    Field Type Description
    id SponsoredConversationUrn (read-only) ID key for the current conversation.
    parentAccount Sponsored Account URN (create-only) The parent account associated with this conversation.
    firstMessageContent Sponsored Message Content URN (update-only) Update the conversation with its first message content.
    headlineText optional string The conversation headline's text. This text is displayed both in the headline view and detail view, specified by the advertiser. When absent headline will display first line of the first message content.
    Field Type Description
    id SponsoredConversationUrn (read-only) ID key for the current conversation.
    parentAccount Sponsored Account URN (create-only) The parent account associated with this conversation.
    firstMessageContent Sponsored Message Content URN (update-only) Update the conversation with its first message content.

    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.

    Create a Sponsored Conversation

    POST https://api.linkedin.com/rest/conversationAds

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

    Successful response will have Status 201 Created and the ID in the x-linkedin-id response header. For example,urn:li:sponsoredConversation:164380864

    Get a Sponsored Conversation

    GET https://api.linkedin.com/rest/conversationAds/{conversationUrn}

    Sample Response

    {
  "id": "urn:li:sponsoredConversation:185204",
  "parentAccount": "urn:li:sponsoredAccount:520866471"
}

    GET https://api.linkedin.com/rest/conversationAds/{conversationUrn}

    Sample Response

    {
  "id": "urn:li:sponsoredConversation:2988042",
  "parentAccount": "urn:li:sponsoredAccount:504513845",
  "headlineText": "subject of this ad"
}

    Update a Sponsored Conversation

    In the following example, the firstMessageContent field is changed to point to the first message of the conversation.

    POST https://api.linkedin.com/rest/conversationAds/{conversationUrn}

    {
  "patch": {
     "$set": {
        "firstMessageContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:185204:14253)"
     }
  } 
}

    A successful response returns a 204 No Content HTTP status code.

    Batch Get Sponsored Conversations

    GET https://api.linkedin.com/rest/conversationAds?ids=List({conversation-urn1},{conversation-urn2})'

    Sample Response

    {
    "statuses": {
        "urn:li:sponsoredConversation:704255": 200,
        "urn:li:sponsoredConversation:703695": 200
    },
    "results": {
        "urn:li:sponsoredConversation:704255": 
         {
            "id": "urn:li:sponsoredConversation:704255",
            "parentAccount": "urn:li:sponsoredAccount:520866471"
            
        },
        "urn:li:sponsoredConversation:703695": 
        {
            "id": "urn:li:sponsoredConversation:703695",
            "parentAccount": "urn:li:sponsoredAccount:520866471",
        }
    },
    "errors": {}
}

    SponsoredMessageContent Schema

    Field Type Description Required
    id SponsoredMessageContentUrn (read-only) The ID key for this message Yes
    sponsoredConversation SponsoredConversationUrn The conversation to which this message belongs Yes
    nextAction SponsoredMessageContentUrn or SponsoredMessageOption[] Indicates whether this message’s next action is another message or an array of options No
    bodySource Either a text string, an AdFormUrn, or a mediaAttachment consisting of an ImageUrn and an optional text string A message can consist of either simple text, or a lead generation form, or an image attachment with an optional attachment text Yes

    SponsoredMessageOption Schema

    Field Type Details Required
    replyType String. Allowed values:
  • LEAD_GENERATION
  • SIMPLE_REPLY
  • EXTERNAL_WEBSITE
  • LEAD_GENERATION_THANK_YOU
    		•  The type of the reply this option will generate Yes
    nextContent SponsoredMessageContentUrn The next message this option will generate No
    optionText String The text displayed on the button Yes
    landingPage URL If specified, the button will redirect to this url No

    Validations

    The following validations occur when managing 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 mediaAttachment:
      • The attachment must be an imageUrn
      • The text length must be less than or equal to 500 characters
    • If nextAction is an array of SponsoredMessageOption, the array must consist of at least 1 SponsoredMessageOption but no more than 5

    Individual SponsoredMessageOption Validations:

    • optionText must be between 1 and 35 characters
    • If the type of the option is LEAD_GENERATION:
      • The nextAction field must exist and is required to point to a SponsoredMessageContent with a bodySource of type leadGenerationForm
    • If the type of the option is LEAD_GENERATION_THANK_YOU:
      • The bodySource of this SponsoredMessageContent must be leadGenerationForm
      • 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 landingPage field must exist
      • The nextAction must not point to a SponsoredMessageContent with a bodySource of type leadGenerationForm
    • If the type of the option is SIMPLE_REPLY:
      • The landingPage must not exist
      • 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

    Note

    {conversationAdsId} is returned in the response header as shown in the first step when you create a Sponsored Conversation using (POST /conversationAds).

    POST https://api.linkedin.com/rest/conversationAds/{conversationAdsId}/sponsoredMessageContents

    {
  "bodySource": {
     "text": "test message"
  }
}

    POST https://api.linkedin.com/rest/conversationAds/{conversationAdsId}/sponsoredMessageContents

    {
  "bodySource": {
    "mediaAttachment": {
      "attachment": "urn:li:image:C5506AQGB9eP_4gNpEQ",
      "text": "test text"
    }
  }
}

    POST https://api.linkedin.com/rest/conversationAds/{conversationAdsId}/sponsoredMessageContents

    {
  "bodySource": {
    "leadGenerationForm": "urn:li:adForm:434835"
  },
  "nextAction":{
    "options":[
      {
        "replyType": "LEAD_GENERATION_THANK_YOU",
        "optionText": "Visit website"
      }
    ]
  }
}

    POST https://api.linkedin.com/rest/conversationAds/{conversationAdsId}/sponsoredMessageContents

    {
  "bodySource": {
    "leadGenerationForm": "urn:li:adForm:434835"
  },
  "nextAction":{
    "options":[
      {
        "replyType": "LEAD_GENERATION_THANK_YOU",
        "optionText": "Visit website"
      },
      {
        "replyType": "SIMPLE_REPLY",
        "nextContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14253)",
        "optionText": "Simple reply"
      },
      {
        "replyType": "EXTERNAL_WEBSITE",
        "optionText": "Visit website",
        "landingPage": "http://www.linkedin.com"
      }
    ]
  }
}

    A successful response returns a 201 Created HTTP status code and the ID in the x-linkedin-id response header, e.g. "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14277)".

    Get Sponsored Message Content

    GET https://api.linkedin.com/rest/conversationAds/{conversationUrn}/sponsoredMessageContents/{messageUrn}

    Sample Response

    {
  "id": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14277)",
  "sponsoredConversation": "urn:li:sponsoredConversation:186604",
  "bodySource": {
    "leadGenerationForm": "urn:li:adForm:434835"
  },
  "nextAction":{
    "options":[
      {
        "replyType": "LEAD_GENERATION_THANK_YOU",
        "optionText": "Visit website"
      },
      {
        "replyType": "SIMPLE_REPLY",
        "nextContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14253)",
        "optionText": "Simple reply"
      },
      {
        "replyType": "EXTERNAL_WEBSITE",
        "optionText": "Visit website",
        "landingPage": "http://www.linkedin.com"
      }
    ]
  }
}

    Get All Sponsored Message Content

    GET https://api.linkedin.com/rest/conversationAds/{conversationUrn}/sponsoredMessageContents

    Sample Response

    {
  "paging": {
    "start": 0,
    "count": 10,
    "links": []
  },
  "elements": [
    {
      "id": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14277)",
      "sponsoredConversation": "urn:li:sponsoredConversation:186604",
      "bodySource": {
        "leadGenerationForm": "urn:li:adForm:434835"
      },
      "nextAction":{
        "options":[
          {
            "replyType": "LEAD_GENERATION_THANK_YOU",
            "optionText": "Visit website"
          },
          {
            "replyType": "SIMPLE_REPLY",
            "nextContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14253)",
            "optionText": "Simple reply"
          },
          {
            "replyType": "EXTERNAL_WEBSITE",
            "optionText": "Visit website",
            "landingPage": "http://www.linkedin.com"
          }
        ]
      }
    },
    {
      "id": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14278)",
      "sponsoredConversation": "urn:li:sponsoredConversation:186604",
      "bodySource": {
        "text": "Sample text"
      },
      "nextAction":{
        "options":[
          {
            "replyType": "EXTERNAL_WEBSITE",
            "optionText": "Other website",
            "landingPage": "http://www.microsoft.com"
          }
        ]
      }
    }
  ]
}

    Update Sponsored Message Content

    In the following example, the bodySource text field is updated.

    POST https://api.linkedin.com/rest/conversationAds/{conversationUrn}/sponsoredMessageContents/{messageUrn}

    {
  "patch": {
    "$set": {
      "bodySource": {
         "text": "New updated text"
      }
    }
  }
}

    A successful response returns a 204 No Content HTTP status code.

    Batch Create Sponsored Message Content

    POST https://api.linkedin.com/rest/conversationAds/{conversationAdsId}/sponsoredMessageContents

    {
  "elements": [ {
    "bodySource": {
      "leadGenerationForm": "urn:li:adForm:434835"
    },
    "nextAction":{
      "options":[
        {
          "replyType": "LEAD_GENERATION_THANK_YOU",
          "optionText": "Visit website"
        },
        {
          "replyType": "SIMPLE_REPLY",
          "nextContent": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14253)",
          "optionText": "Simple reply"
        },
        {
          "replyType": "EXTERNAL_WEBSITE",
          "optionText": "Visit website",
          "landingPage": "http://www.linkedin.com"
        }
      ]
    }
  },{
    "bodySource": {
      "text": "Sample text"
    },
    "nextAction":{
      "options":[
        {
          "replyType": "EXTERNAL_WEBSITE",
          "optionText": "Other website",
          "landingPage": "http://www.microsoft.com"
        }
      ]
    }

  }]
}

    Batch Update Sponsored Message Content

    POST https://api.linkedin.com/rest/conversationAds/{conversationUrn}/sponsoredMessageContents?ids=List({message-urn1},{message-urn2})

    {
  "entities": {
    "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14277)": {
      "patch": {
        "$set": {
          "bodySource": {
            "text": "New updated text"
          }
        }
      }
    },
    "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14278)": {
      "patch": {
        "$set": {
          "bodySource": {
            "text": "New updated text2"
          }
        }
      }
    }
  }
}

    Sample Response

    {
    "elements": [
        {
            "location": "/conversationAds/urn:li:sponsoredConversation:186604/sponsoredMessageContents/urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14250)",
            "status": 204,
            "id": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14250)"
        },
        {
            "location": "/conversationAds/urn:li:sponsoredConversation:186604/sponsoredMessageContents/urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14251)",
            "status": 204,
            "id": "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14251)"
        }
    ]
}

    Batch Delete Sponsored Message Content

    DELETE https://api.linkedin.com/rest/conversationAds/{conversationUrn}/sponsoredMessageContents?ids=List({message-urn1},{message-urn2})'

    {
  "results": {
    "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14277)": {
      "status": 204
    },
    "urn:li:sponsoredMessageContent:(urn:li:sponsoredConversation:186604,14278)": {
      "status": 204
    }
  },
  "errors": {}
}

    References

    Legacy /sponsoredConversations API