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
| Key | Type | Description |
|---|---|---|
| type | String | The type of object (news-item). |
| id | String | The unique identifier for the news item which is given by Intercom. |
| workspace_id | String | The id of the workspace which the news item belongs to. |
| title | String | The title of the news item. |
| body | String | See more on what we accept in the Supported HTML table below. |
| sender_id | String | The id of the sender of the news item. Must be a teammate on the workspace. |
| state | String | Either "live" or "draft". News items will not be visible to your users in the assigned newsfeeds until they are set live. |
| newsfeed_assignments | Newsfeed Assignment Object [] | List of newsfeed_assignments to assign to the specified newsfeed. See Newsfeed Assignment Object. |
| labels | String[] | Label names displayed to users to categorize the news item. |
| cover_image_url | URL | URL of the image used as cover. Must have .jpg or .png extension. |
| reactions | String[] | Ordered list of emoji reactions to the news item. When empty, reactions are disabled. |
| deliver_silently | boolean | When set to true, the news item will appear in the messenger newsfeed without showing a notification badge. |
| created_at | Timestamp | Timestamp for when the news item was created. |
| updated_at | Timestamp | Timestamp 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
| Tag | What does it do? | Additional Details |
|---|---|---|
<p> | Paragraph | All text must be placed within paragraph tags. |
<br> | Line break | Supported in-line. |
<hr> | Horizontal rule | NA |
<h1> <h2> | Heading | Only these two header tags are supported. All others will be replaced with <h2>. |
<a> | Link | An image can be placed in-between the link tags. |
<img> | Image | Images 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> | List | Lists 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> | Table | Needs 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> | Video | src 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
| Class | What does it do? | Where does it work? |
|---|---|---|
| intercom-align-center | Center Alignment | On tag level: Headers, Paragraphs. On wrapping div: Images, Buttons. |
| intercom-h2b-button | Button | On tag level: Links |
Unsupported HTML
| Tag | What does it do? | What do we do? |
|---|---|---|
<dl> | Definition List | Hard fail - 400 Bad Request |
<ul> or <ol> | Nested lists | Hard fail - 400 Bad Request |
<iframe> | iFrame Unsupported video | Hard fail - 400 Bad Request |
<div> <span> | Content division | Replace with <p> |
<h3> to <h6> | Heading | Replace with <h2> |
<form> | Form | Remove from content |
<input> <textarea> | Input | Remove from content |
<script> | Javascript Script | Remove from content |
<head> <html> <footer> etc. | All other tags | Remove from content Internals replaced with <p> |
Newsfeed Object
| Key | Type | Description |
|---|---|---|
| type | String | The type of object - newsfeed. |
| id | String | The unique identifier for the newsfeed which is given by Intercom. |
| workspace_id | String | The id of the workspace which the newsfeed belongs to. |
| title | String | The name of the newsfeed. This name will never be visible to your users. |
| state | String | Either "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_at | Timestamp | Timestamp for when the newsfeed was created. |
| updated_at | Timestamp | Timestamp 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.
| Key | Type | Description |
|---|---|---|
| newsfeed_id | String | The unique identifier for the newsfeed which is given by Intercom. |
| published_at | Timestamp | Publish 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_idto assign the news item to the news center.