API ReferenceBuilding AppsInstalling IntercomAPI & Webhook ReferenceCanvas Kit Reference
DocsApp StoreForumBlogYour Apps

The News Item & newsfeed models

The News API allows you to easily manage news items and newsfeeds.

News are shared through news items which can be assigned to multiple newsfeeds.

A newsfeed is a collection of news items, targeted to a specific audience. Newsfeeds currently cannot be edited through the API, please refer to this article to set up your newsfeeds in Intercom.

News Item Object

KeyTypeDescription
typeStringThe type of object (news-item).
idStringThe unique identifier for the news item which is given by Intercom.
workspace_idStringThe id of the workspace which the news item belongs to.
titleStringThe title of the news item.
bodyStringSee more on what we accept in the Supported HTML table below.
sender_idStringThe id of the sender of the news item. Must be a teammate on the workspace.
stateStringEither "live" or "draft".
News items will not be visible to your users in the assigned newsfeeds until they are set live.
newsfeed_assignmentsNewsfeed Assignment Object []List of newsfeed_assignments to assign to the specified newsfeed. See Newsfeed Assignment Object.
labelsString[]Label names displayed to users to categorize the news item.
cover_image_urlURLURL of the image used as cover. Must have .jpg or .png extension.
reactionsString[]Ordered list of emoji reactions to the news item. When empty, reactions are disabled.
deliver_silentlybooleanWhen set to true, the news item will appear in the messenger newsfeed without showing a notification badge.
created_atTimestampTimestamp for when the news item was created.
updated_atTimestampTimestamp for when the news item was last updated.

The table below defines the subset of HTML accepted when creating or updating a news item. Over time we may add support for new HTML elements and attributes, since this will not constitute a breaking change, we advise any client code to support the full HTML specification when reading news item content.

Supported HTML

TagWhat does it do?Additional Details
<p>ParagraphAll text must be placed within paragraph tags.
<br>Line breakSupported in-line.
<hr>Horizontal ruleNA
<h1> <h2>HeadingOnly these two header tags are supported. All others will be replaced with <h2>.
<a>LinkAn image can be placed in-between the link tags.
<img>ImageImages will be uploaded to Intercom and we'll use an Intercom link to display these.
If these fail to upload then we'll hard fail and return 400 Bad Request.
<ul> <ol> <li>ListLists must contain at least one non-empty <li> element.

<li> elements can contain plain text, or any other supported HTML tags, except <table>.

If these criteria aren't met, then the news item will hard fail and return 400 Bad request.
<table>TableNeeds to have at least one row and one cell.
Can contain any other supported HTML tags, except another <table> within.
If these criteria aren't met then it will hard fail and return 400 Bad request.
<iframe>Videosrc must be for a supported video embed link.
Only works for Youtube, Wistia, Vimeo, Loom, Vidyard or StreamIO.
<pre> <code>Pre-formatted code
<b> <strong>Bold
<i> <em>Italic

Supported CSS

ClassWhat does it do?Where does it work?
intercom-align-centerCenter AlignmentOn tag level: Headers, Paragraphs.
On wrapping div: Images, Buttons.
intercom-h2b-buttonButtonOn tag level: Links

Unsupported HTML

TagWhat does it do?What do we do?
<dl>Definition ListHard fail - 400 Bad Request
<ul> or <ol>Nested listsHard fail - 400 Bad Request
<iframe>iFrame
Unsupported video
Hard fail - 400 Bad Request
<div> <span>Content divisionReplace with <p>
<h3> to <h6>HeadingReplace with <h2>
<form>FormRemove from content
<input> <textarea>InputRemove from content
<script>Javascript ScriptRemove from content
<head> <html> <footer> etc.All other tagsRemove from content
Internals replaced with <p>

Newsfeed Object

KeyTypeDescription
typeStringThe type of object - newsfeed.
idStringThe unique identifier for the newsfeed which is given by Intercom.
workspace_idStringThe id of the workspace which the newsfeed belongs to.
titleStringThe name of the newsfeed. This name will never be visible to your users.
stateStringEither "live" or "draft".
A newsfeed is in live state when at least one of its assigned news items is in live state.
A newsfeed is in draft state when all of its assigned news items are in draft or paused state.
created_atTimestampTimestamp for when the newsfeed was created.
updated_atTimestampTimestamp for when the newsfeed was last updated.

Newsfeed assignment object

A news item can be assigned to multiple newsfeeds, use the newsfeed_assignments array on the news item model to assign a news item to a newsfeed through the newsfeed assignment model.

KeyTypeDescription
newsfeed_idStringThe unique identifier for the newsfeed which is given by Intercom.
published_atTimestampPublish date of the news item on the newsfeed, use this field if you want to set a publish date in the past (e.g. when importing existing news items).
Publish dates cannot be in the future, to schedule news items use the dedicated feature in app (see this article).
On write, this field will be ignored if the news item state is "draft".

📘

How do I assign a news item to the news center newsfeed?

The newsfeed list returned by the list API will always include a news center newsfeed. Use its newsfeed_id to assign the news item to the news center.