# Get Announcement Articles ## Overview The Get Announcement Articles API returns a portal's announcement articles. Only displayable announcement articles in the portal are returned. ## Prerequisites * For an article to display or be returned, set the Article type’s parameter, “Include in browse on portals,” to "Yes". * Agents without a user profile and customers in a portal without a default user profile only have access to articles that: * Do not contain any access tags. * Do not contain any publish views. * Contain publish views without any associated tags. * Agents with a user profile and customers in a portal with a default user profile have access to articles that: * Do not contain any access tags. * Do not contain any publish views. * Contain publish views without any associated tags. * Contain access tags that are also in the assigned user profiles. * Contain publish views with associated tags that are also in the assigned user profiles. ## Permissions * Agents with the following assigned actions can view updates to articles currently being processed in workflows: * View Author Portal – Allows agents to view updates to articles at any stage in a workflow. * View Staging Portal – Allows agents to view updates to articles in the Staging stage or a subsequent stage in a workflow. Endpoint: GET /portals/{portalID}/articles/announcements Security: oAuthUser, oAuthOnBehalfOfUser, oAuthCustomer, oAuthOnBehalfOfCustomer, oAuthAnonymousCustomer ## Description: - `Overview` () The Get Announcement Articles API returns a portal's announcement articles. Only displayable announcement articles in the portal are returned. - `Prerequisites` () For an article to display or be returned, set the Article type’s parameter, “Include in browse on portals,” to "Yes".Agents without a user profile and customers in a portal without a default user profile only have access to articles that:Do not contain any access tags.Do not contain any publish views.Contain publish views without any associated tags.Agents with a user profile and customers in a portal with a default user profile have access to articles that:Do not contain any access tags.Do not contain any publish views.Contain publish views without any associated tags.Contain access tags that are also in the assigned user profiles.Contain publish views with associated tags that are also in the assigned user profiles. - `Permissions` () Agents with the following assigned actions can view updates to articles currently being processed in workflows:View Author Portal – Allows agents to view updates to articles at any stage in a workflow.View Staging Portal – Allows agents to view updates to articles in the Staging stage or a subsequent stage in a workflow. ## Versioning This operation is available in API version `4.0`. ## Security: - `oAuthUser` (unknown) oauth2 scopes: https://api.egain.cloud/auth/knowledge.portalmgr.read - `oAuthOnBehalfOfUser` (unknown) oauth2 scopes: https://api.egain.cloud/auth/knowledge.portalmgr.onbehalfof.read - `oAuthCustomer` (unknown) oauth2 scopes: https://api.egain.cloud/auth/knowledge.portalmgr.read - `oAuthOnBehalfOfCustomer` (unknown) oauth2 scopes: https://api.egain.cloud/auth/knowledge.portalmgr.onbehalfof.read - `oAuthAnonymousCustomer` (unknown) oauth2 scopes: https://api.egain.cloud/auth/knowledge.portalmgr.read ## Path parameters: - `portalID` (string, required) The ID of the portal being accessed.

A portal ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits. ## Query parameters: - `$filter[tags]` (string) A comma separated list of Tag / Tag Group IDs. The query results will be filtered by the tags that are specified.

Tag IDs and Tag Group IDs can be mixed together. - `articleResultAdditionalAttributes` (array) The attributes of an Article to be returned *in addition to* the default list of attributes, listed below. Multiple additional attributes can be specified using a comma-separated list. Passing 'all' will return all attributes. #### Default Attributes These Article attributes are always returned: | Name | Description | ---- | ----------- | id | The ID of the Article. | name | The name of the Article. | articleType | The Article Type and its attributes. | createdBy | The ID, first name, middle name and last name of the user that created the Article. | createdDate | The date that the Article was created. | hasAttachments | True: The Article has one or more attachments.
False: The Article does not have any attachments. | languageCode | The language code of the Article language. | modifiedBy | The ID, first name, middle name and last name of the user that last modified the Article. | modifiedDate | The date that the Article was last modified on. | link | The link object, used to retrieve the details of the Article. | versionId | The ID of the Article version that is returned. - `articleResultExtendedAttributes` (array) Specifies extended attributes of an Article Result to be returned in the response. This parameter is used for specific metadata fields that are not included in the default response or the standard additional attributes list. **Note:** The list of supported values for this parameter may be expanded in the future as more fields are added to the article result schema. | Name | Description | ---- | ----------- | availabilityDate | The date and time when the article becomes available for viewing. - `workflowMilestone` (string) For agents with the View Author Portal or View Staging Portal actions, this determines which version of the Article is returned.
  • 'Authoring' returns the most recent version of an Article checked-in by an author.
  • 'Staging' returns the updated version currently being processed in a workflow.
  • 'Publish' returns the most recently published version.
    • - `$lang` (string) The language used for a resource. Resources available in different languages may differ from each other. If $lang is not passed, then the portal's default language is used. - `$pagenum` (integer) Pagination parameter that specifies the page number of results to be returned. Used in conjunction with $pagesize. - `$pagesize` (integer) Pagination parameter that specifies the number of results per page. Used in conjunction with $pagenum. ## Header parameters: - `x-egain-activity-id` (string) A unique numeric interaction identifier from eGain. - `x-ext-integration-id` (string) The unique numeric identifier for a tenant, used in self-service functionality as well as third-party integrations.

    *Note: The x-ext-integration-id and x-ext-interaction-id headers must always be provided together and cannot be supplied independently.

    The x-egain-activity-id may be provided on its own, or it may be provided along with both x-ext-integration-id and x-ext-interaction-id.* - `x-ext-interaction-id` (string) A unique interaction identifier from other CRM applications.

    *Note: The x-ext-integration-id and x-ext-interaction-id headers must always be provided together and cannot be supplied independently.

    The x-egain-activity-id may be provided on its own, or it may be provided along with both x-ext-integration-id and x-ext-interaction-id.* - `Accept-Language` (string, required) The Language locale accepted by the client (used for locale specific fields in resource representation and in error responses). ## Response 200: - `200` (unknown) Success ## Response 200 fields (application/json): - `articles` (array) Article details - `articles.id` (string) The ID of the Article.An Article ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits. - `articles.articleType` (object) The type of the Article and its attributes. - `articles.articleType.articleCategoryId` (integer) Specifies the article category ID. - `articles.articleType.typeName` (string) Indicates the article type name. - `articles.articleType.useStructuredAuthoring` (boolean) Indicates whether structured authoring is enabled for this article type, requiring content to be created using predefined fields - `articles.articleType.articleTypeId` (string) The ID of the Article Type. Example: 932100000002020 - `articles.articleKeywords` (string) A comma-separated list of keywords associated with this Article. 1 KB max size limit. - `articles.articleSummary` (string) A brief summary of the Article, provided as metadata. 1 KB max size limit. - `articles.availabilityDate` (string) The date on which the Article version is available. - `articles.averageRating` (number) The average rating of the Article. - `articles.createdBy` (object) - `articles.createdBy.id` (string) The ID of the user that created this resource. - `articles.createdBy.userName` (string) The resource creator's username. - `articles.createdBy.firstName` (string) The resource creator's first name. - `articles.createdBy.middleName` (string) The resource creator's middle name. - `articles.createdBy.lastName` (string) The resource creator's last name. - `articles.modifiedBy` (object) - `articles.modifiedBy.id` (string) The ID of the user that modified this resource. - `articles.modifiedBy.userName` (string) The resource modifier's username. - `articles.modifiedBy.firstName` (string) The resource modifier's first name. - `articles.modifiedBy.middleName` (string) The resource modifier's middle name. - `articles.modifiedBy.lastName` (string) The resource modifier's last name. - `articles.ownedBy` (object) - `articles.ownedBy.id` (string) The ID of the user that owns this resource. - `articles.ownedBy.userName` (string) The resource owner's username. - `articles.ownedBy.firstName` (string) The resource owner's first name. - `articles.ownedBy.middleName` (string) The resource owner's middle name. - `articles.ownedBy.lastName` (string) The resource owner's last name. - `articles.createdDate` (string) - `articles.customAttributes` (array) A list of custom attributes. - `articles.customAttributes.name` (string) The custom attribute's name. - `articles.customAttributes.value` (array) The custom attribute's values. - `articles.customAttributes.type` (string) The custom attribute's type. Enum: "STRING", "INTEGER", "BOOLEAN", "DATETIME" - `articles.description` (string) A description of the Article. The maximum allowed Article description size is 1 KB. - `articles.hasAttachments` (boolean) Indicates whether the Article has any attachments. - `articles.isSubscribed` (boolean) Indicates whether the Article is subscribed for notifications. - `articles.modifiedDate` (string) The date on which the Article was last modified. - `articles.languageCode` (string) Language code of the resource's language. Enum: "en-US", "fr-FR", "en-GB", "es-ES", "it-IT", "nl-NL", "da-DA", "sv-SE", "pt-PT", "fi-FI", "no-NB", "no-NN", "ja-JA", "de-DE", "pt-BR", "zh-CN", "zh-TW", "ko-KO", "ru-RU", "el-EL", "tr-TR", "pl-PL", "cs-CS", "sk-SK", "hu-HU", "sr-SR", "ar-SA", "hr-HR", "ro-RO", "th-TH" - `articles.link` (object) Defines the relationship between this resource and another object. - `articles.link.rel` (string) Defines the relationship between a linked resource and the current object—for example a resource type name such as *article* or *topic* as defined by the API for that link. - `articles.link.href` (string) The URL that specifies the link's destination. - `articles.imageURL` (string) The URL of the image that is present in the Article version. It is used as the thumbnail image for the Article. - `articles.name` (string) The name of the Article. - `articles.timesRated` (integer) The number of times that this Article has been rated. - `articles.topicBreadcrumb` (array) A list of topics from the root topic to this Article. There may be multiple paths. - `articles.topicBreadcrumb.topicSummary` (array) An instance of TopicSummary. - `articles.topicBreadcrumb.topicSummary.id` (string) The alphanumeric ID of the topic.A topic ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits. Example: PROD-1921 - `articles.topicBreadcrumb.topicSummary.name` (string) The name of the topic. - `articles.versionId` (string) The ID of this version of the Article. - `articles.workflow` (object) The Article's workflow. - `articles.workflow.stages` (array) An array of stages for the workflow. - `articles.workflow.stages.name` (string) The name of the stage. - `articles.workflow.stages.milestone` (object) A resource's workflow milestone. - `articles.workflow.stages.milestone.name` (object) The identifiers of the milestone. - `articles.workflow.stages.milestone.name.value` (string) The name of the milestone. - `articles.workflow.stages.milestone.name.displayValue` (string) The readable name of the milestone. - `articles.compliance` (object) This schema contains the compliance details for an Article. - `articles.compliance.startDate` (object) The start date for the Article. - `articles.compliance.startDate.date` (string, required) The date in the format YYYY-MM-DDTHH:MM:SS. - `articles.compliance.dueDate` (object) The end date for the Article. - `articles.compliance.dueDate.date` (string, required) The date in the format YYYY-MM-DDTHH:MM:SS. - `articles.personalization` (object) Personalization allows the filtering of search results and controls the access to articles and article editions. - `articles.personalization.accessTags` (object) - `articles.personalization.accessTags.tagCategory` (array) An array of tag categories. Note that the total number of tag categories cannot exceed 20. - `articles.personalization.accessTags.tagCategory.name` (string) The name of the tag category. - `articles.personalization.accessTags.tagCategory.id` (string) The ID of the tag category. A tag category ID is composed of a 4-letter prefix, followed by a dash and 4-15 digits. - `articles.personalization.accessTags.tagCategory.tags` (object) - `articles.personalization.accessTags.tagCategory.tags.tag` (array) An array of tags. - `articles.personalization.accessTags.tagCategory.tags.tag.name` (string) Example: Blue - `articles.personalization.accessTags.tagCategory.tags.tag.id` (string) Example: PROD-13206 - `articles.personalization.accessTags.tagCategory.tagGroups` (object) - `articles.personalization.accessTags.tagCategory.tagGroups.tagGroup` (array) An array of tag groups. - `articles.personalization.accessTags.tagCategory.tagGroups.tagGroup.name` (string) - `articles.personalization.accessTags.tagCategory.tagGroups.tagGroup.id` (string) Example: PROD-14566 - `articles.personalization.filters` (object) - `articles.personalization.filters.tagCategory` (array) An array of tag categories. Note that the total number of tag categories cannot exceed 20. - `articles.personalization.publishViews` (object) - `articles.personalization.publishViews.publishView` (array) Publish views allow authors to tailor the contents of an article to different audiences by controlling visibility of certain article content using tags.The total number of publish views is limited to 20. - `articles.personalization.publishViews.publishView.name` (string) name of the publish view - `articles.personalization.publishViews.publishView.id` (string) Example: PROD-12446 - `articles.personalization.publishViews.publishView.tagCategories` (array) Tag categories are comprised of both tags and tag groups.Note that the total number of tag and tag groups cannot exceed 20. - `articles.personalization.publishViews.publishView.tagCategories.tagCategory` (array) - `paginationInfo` (object) - `paginationInfo.count` (integer, required) The total number of items. - `paginationInfo.pagenum` (integer, required) The page number requested. Page numbers start from 1. - `paginationInfo.pagesize` (integer, required) The number of objects requested per page. The maximum number of objects per page is 75. - `paginationInfo.link` (array) Can include the *prev* and *next* link. ## Response 204: - `204` (unknown) No Content ## Response 400: - `400` (unknown) Bad Request ## Response 400 fields (application/json): - `code` (string, required) A string that follows the pattern *{integer}-{integer}*. The first *{integer}* is the http status code. This code as a whole is unique. * For example, error codes "400-101" and "404-101" are distinctly different. - `developerMessage` (string, required) A summary of the error. - `details` (array) - `details.key` (string, required) - `details.value` (string) - `userMessage` (string) UI friendly messages are only supported by some APIs. * The client must explicitly request UI friendly messages by passing the *X-egain-error-message=yes* header. ## Response 401: - `401` (unknown) Unauthorized ## Response 401 fields (application/json): - `code` (string, required) A string that follows the pattern *{integer}-{integer}*. The first *{integer}* is the http status code. This code as a whole is unique. * For example, error codes "400-101" and "404-101" are distinctly different. - `developerMessage` (string, required) A summary of the error. - `details` (array) - `details.key` (string, required) - `details.value` (string) - `userMessage` (string) UI friendly messages are only supported by some APIs. * The client must explicitly request UI friendly messages by passing the *X-egain-error-message=yes* header. ## Response 403: - `403` (unknown) Forbidden ## Response 403 fields (application/json): - `code` (string, required) A string that follows the pattern *{integer}-{integer}*. The first *{integer}* is the http status code. This code as a whole is unique. * For example, error codes "400-101" and "404-101" are distinctly different. - `developerMessage` (string, required) A summary of the error. - `details` (array) - `details.key` (string, required) - `details.value` (string) - `userMessage` (string) UI friendly messages are only supported by some APIs. * The client must explicitly request UI friendly messages by passing the *X-egain-error-message=yes* header. ## Response 404: - `404` (unknown) Not Found ## Response 404 fields (application/json): - `code` (string, required) A string that follows the pattern *{integer}-{integer}*. The first *{integer}* is the http status code. This code as a whole is unique. * For example, error codes "400-101" and "404-101" are distinctly different. - `developerMessage` (string, required) A summary of the error. - `details` (array) - `details.key` (string, required) - `details.value` (string) - `userMessage` (string) UI friendly messages are only supported by some APIs. * The client must explicitly request UI friendly messages by passing the *X-egain-error-message=yes* header. ## Response 406: - `406` (unknown) Not acceptable ## Response 406 fields (application/json): - `code` (string, required) A string that follows the pattern *{integer}-{integer}*. The first *{integer}* is the http status code. This code as a whole is unique. * For example, error codes "400-101" and "404-101" are distinctly different. - `developerMessage` (string, required) A summary of the error. - `details` (array) - `details.key` (string, required) - `details.value` (string) - `userMessage` (string) UI friendly messages are only supported by some APIs. * The client must explicitly request UI friendly messages by passing the *X-egain-error-message=yes* header. ## Response 500: - `500` (unknown) Internal server error ## Response 500 fields (application/json): - `code` (string, required) A string that follows the pattern *{integer}-{integer}*. The first *{integer}* is the http status code. This code as a whole is unique. * For example, error codes "400-101" and "404-101" are distinctly different. - `developerMessage` (string, required) A summary of the error. - `details` (array) - `details.key` (string, required) - `details.value` (string) - `userMessage` (string) UI friendly messages are only supported by some APIs. * The client must explicitly request UI friendly messages by passing the *X-egain-error-message=yes* header. ## Response 200 examples: - `Summary Attributes` (unknown) - `All Attributes` (unknown) ## Response 400 examples: - `Required Attribute missing` (unknown) Required query parameter is missing. - `Unallowed attribute value` (unknown) One of the attributes has a value which is not allowed. ## Response 401 examples: - `Invalid Authorization` (unknown) Invalid or expired authorization. Generate a new authorization header and try again. ## Response 403 examples: - `Required Scope Missing` (unknown) User doesn't have the required scope to call this API. Refer to the API documentation regarding user scope assignment for more information. ## Response 404 examples: - `Resource Not Found` (unknown) Resource not found. ## Response 406 examples: - `Not Acceptable` (unknown) ## Response 500 examples: - `Internal Server Error` (unknown)