What Can GraphQL Mutations do for AnnounceKit?

GraphQL Queries are special commands for you to run in our IDE.

These special commands are used to change information and settings for your projects.

While all of the options for mutations can be enabled through our dashboard, GraphQL is mainly used by developers for API development at a fast pace.

How to use these mutations?

Below is a documentation for all of the mutations that can be run in our GraphQL IDE, along with their descriptions, arguments, what the mutation will return, fields within the mutations, and a code example.

Arguments are purple fields below the mutations, and while some of them are optional, the most important ones are required arguments. Without them, the mutation will not work.

Return Type is an explanation of what the mutation will return in the code, a.k.a. what it will change in a project.

Fields in mutations are yellow fields to be filled with information you want to change for that mutation. For example;

saveLabel is a mutation for creating and saving a label in your project.

project_id: ID!

label_id: ID

name: String!

color: String! are arguments you will provide to start the mutation. While some are optional, important fields like “project_id” are required so that the mutation can know which project it will save the label for.

Label is the field with information and details about the label you want to create for your project. As you can see, an ID, name, and color is required for your label to be created.Arguments are subfields for queries, and while some arguments among queries are optional, make sure to complete the required arguments, as without them, you cannot run the queries.

Each of these mutations below is used by going into our IDE located here.

Posts and Templates

savePost

Description: Saves a post with various attributes.

Arguments:

project_id (required): ID of the project where the post will be saved.
contents (required): An array of PostContentInput objects representing the content of the post.
user_id: ID of the user associated with the post.
post_id: ID of an existing post to be updated (optional).
visible_at: Date when the post should become visible.
expire_at: Date when the post should expire.
is_draft: Boolean indicating if the post is a draft.
is_pushed: Boolean indicating if the post has been pushed.
is_pinned: Boolean indicating if the post is pinned.
image_id: ID of the image associated with the post.
external_url: URL associated with the post.
labels: An array of label IDs associated with the post.
segment_filters: JSON object representing segment filters for targeting the post.
flags: An array of flags associated with the post.
type: Type of the post.
is_paused: Boolean indicating if the post is paused.

Return Type: Returns the saved post.

{
"mutation": "savePost",
"variables": {
"project_id": "12345",
"contents": [
{
"language": "en",
"title": "New post",
"body": "This is a new post"
}
],
"user_id": "user123",
"is_draft": false,
"is_pushed": true,
"is_pinned": false
}
}

deletePost

Description: Deletes a post.

Arguments:

project_id (required): ID of the project where the post is located.
post_id (required): ID of the post to be deleted.

Return Type: Returns a boolean indicating the success of deleting the post.

{
"mutation": "deletePost",
"variables": {
"project_id": "12345",
"post_id": "54321"
}
}

updatePostLocale

Description: Updates the locale-specific attributes of a post.

Arguments:

project_id (required): ID of the project where the post is located.
post_id (required): ID of the post to be updated.
locale_id (required): ID of the locale associated with the post.
title (required): Updated title of the post.
body (required): Updated body/content of the post.

Return Type: Returns a boolean indicating the success of updating the post locale.

Example:

{
"mutation": "updatePostLocale",
"variables": {
"project_id": "12345",
"post_id": "54321",
"locale_id": "en",
"title": "Updated Title",
"body": "Updated Body"
}
}

deletePostLocale

Description: Deletes a locale-specific version of a post.

Arguments:

project_id (required): ID of the project where the post is located.
post_id (required): ID of the post to be deleted.
locale_id (required): ID of the locale associated with the post.

Return Type: Returns a boolean indicating the success of deleting the post locale.

Example:

{
"mutation": "deletePostLocale",
"variables": {
"project_id": "12345",
"post_id": "54321",
"locale_id": "en"
}
}

savePostTemplate

Description: Saves a post template with a title and body.

Arguments:

project_id (required): ID of the project where the post template will be saved.
post_template_id: ID of an existing post template to be updated (optional).
title (required): Title of the post template.
body (required): Body/content of the post template.

Return Type: Returns the saved post template.

Example:

{
"mutation": "savePostTemplate",
"variables": {
"project_id": "12345",
"post_template_id": "54321",
"title": "Template Title",
"body": "Template Body"
}
}

deletePostTemplate

Description: Deletes a post template.

Arguments:

project_id (required): ID of the project where the post template is located.
post_template_id (required): ID of the post template to be deleted.

Return Type: Returns a boolean indicating the success of deleting the post template.

Example:

{
"mutation": "deletePostTemplate",
"variables": {
"project_id": "12345",
"post_template_id": "54321"
}
}

autoGeneratePostContents

Description: Automatically generates post contents based on the provided options.

Arguments:

project_id (required): ID of the project to generate post contents for.
locale_id (required): ID of the locale for which to generate post contents.
type (required): String representing the type of post contents to generate.
options (required): JSONObject containing the options for generating post contents.
temperature (optional): Float representing the temperature for generating post contents.

Return Type: Returns an array of AutoGeneratedPostContent objects.

Example:

{
"mutation": "autoGeneratePostContents",
"variables": {
"project_id": "project123",
"locale_id": "locale123",
"type": "news",
"options": {
"category": "technology",
"length": 5
},
"temperature": 0.8
}
}

Reactions, Feedback, and Subscriptions

reactToPost

Description: Performs a reaction to a post by a user.

Arguments:

user_id (optional): ID of the user performing the reaction.
post_id (required): ID of the post to react to.
reaction (required): String representing the reaction.
fields (optional): Additional fields for the reaction, provided as a JSON object.
source (optional): Source of the action, defaults to "widget".

Return Type: ReactToPostResult object.

Fields:

user_id (required): ID of the user who performed the reaction.
post_id (required): ID of the post that was reacted to.
reaction (required): String representing the reaction.

Example:

{
"mutation": "reactToPost",
"variables": {
"user_id": "user123",
"post_id": "post456",
"reaction": "like",
"fields": {
"comment": "Great post!"
},
"source": "widget"
}
}

feedbackToPost

Description: Provides feedback to a post by a user.

Arguments:

user_id (optional): ID of the user providing the feedback.
post_id (required): ID of the post to provide feedback to.
feedback (required): String representing the feedback.
fields (optional): Additional fields for the feedback, provided as a JSON object.
source (optional): Source of the action, defaults to "widget".

Return Type: Returns a FeedbackToPostResult object representing the result of the feedback.

FeedbackToPostResult Fields:

user_id (required): ID of the user who provided the feedback.
post_id (required): ID of the post that received the feedback.
feedback (required): String representing the feedback.

Example:

{
"mutation": "feedbackToPost",
"variables": {
"user_id": "user123",
"post_id": "post456",
"feedback": "Great post!",
"fields": {
"rating": 5
},
"source": "widget"
}
}

subscribeToProject

Description: Subscribes a user to a project.

Arguments:

user_id (optional): ID of the user to subscribe.
project_id (required): ID of the project to subscribe to.
email (required): Email address of the user.
fields (optional): Additional fields for the subscription, provided as a JSON object.
source (optional): Source of the action, defaults to "widget".

Return Type: Returns a SubscribeToProjectResult object representing the result of the subscription.

SubscribeToProjectResult Fields

user_id (required): ID of the user who subscribed.
email (required): Email address of the user.

Example:

{
"mutation": "subscribeToProject",
"variables": {
"user_id": "user123",
"project_id": "project456",
"email": "[email protected]",
"fields": {
"subscription_type": "monthly"
},
"source": "widget"
}
}

Labels and Label Order

saveLabel

Description: Saves or updates a label for a project.

Arguments:

· project_id (required): ID of the project to which the label belongs.
· label_id: ID of the label (optional).
· name (required): Name of the label.
· color (required): Color of the label.

Return Type: Returns the saved/updated label information.

Label Fields:

· id: ID of the label.
· name: Name of the label.
· color: Color of the label.

Example:

{
"mutation": "saveLabel",
"variables": {
"project_id": "12345",
"label_id": "54321",
"name": "Label Name",
"color": "#FF0000"
}
}

saveLabelOrder

Description: Saves the order of labels for a project.

Arguments:

project_id (required): ID of the project for which the label order is being saved.
label_ids (required): Array of label IDs representing the desired order.

Return Type: Returns the updated list of labels in the specified order.

Label Fields:

id: ID of the label.
name: Name of the label.
color: Color of the label.

Example:

{
"mutation": "saveLabelOrder",
"variables": {
"project_id": "12345",
"label_ids": ["labelId1", "labelId2", "labelId3"]
}
}

deleteLabel

Description: Deletes a label from a project.

Arguments:

project_id (required): ID of the project from which the label is being deleted.
label_id (required): ID of the label to be deleted.

Return Type: Returns the result of the deletion operation.

Result Fields:

type: Result type indicating success or failure.
message: Result message providing additional information.

Example:

{
"mutation": "deleteLabel",
"variables": {
"project_id": "12345",
"label_id": "labelIdToDelete"
}
}

Widgets and Widget Themes

ensureWidget

Description: Ensures the existence of a widget for a project.

Arguments:

project_id (required): ID of the project.
mode (required): Mode of the widget.

Return Type: Returns the widget.

Example:

{
"mutation": "ensureWidget",
"variables": {
"project_id": "12345",
"mode": "light"
}
}

saveWidget

Description: Saves a widget with various attributes.

Arguments:

project_id (required): ID of the project where the widget will be saved.
widget_id: ID of an existing widget to be updated (optional).
mode (required): Mode of the widget.
name: Name of the widget.
action (required): Action associated with the widget.
options (required): JSON object representing options for the widget.
theme: Theme settings for the widget.
version: Version number of the widget.
ga_cookie_status (required): GA cookie status for the widget.
content_to_show (required): Content to be shown in the widget.

Return Type: Returns the saved widget.

Example:

{
"mutation": "saveWidget",
"variables": {
"project_id": "12345",
"widget_id": "54321",
"mode": "light",
"name": "My Widget",
"action": "click",
"options": {},
"theme": {},
"version": 1,
"ga_cookie_status": "enabled",
"content_to_show": "Widget Content"
}
}

saveWidgetTheme

Description: Saves the theme settings for a widget.

Arguments:

project_id (required): ID of the project where the widget is located.
widget_id (required): ID of the widget to update.
theme (required): JSON object representing the theme settings for the widget.

Return Type: Returns the updated widget.

Example:

{
"mutation": "saveWidgetTheme",
"variables": {
"project_id": "12345",
"widget_id": "54321",
"theme": {}
}
}

deleteWidget

Description: Deletes a widget.

Arguments:

project_id (required): ID of the project where the widget is located.
widget_id (required): ID of the widget to be deleted.

Return Type: Returns a result indicating the success of deleting the widget.

Example:

{
"mutation": "deleteWidget",
"variables": {
"project_id": "12345",
"widget_id": "54321"
}
}

Feature Requests and Comments

voteFeatureRequestPublic

Description: Votes or unvotes a public feature request by providing the feature request ID.

Arguments:

feature_request_id (required): ID of the feature request to vote or unvote.
isUnvote (optional): Boolean flag indicating whether to unvote the feature request. Defaults to false.

Return Type: Returns a Boolean value indicating whether the voting or unvoting was successful.

Example:

{
"mutation": "voteFeatureRequestPublic",
"variables": {
"feature_request_id": "feature123",
"isUnvote": false
}
}

commentFeatureRequestPublic

Description: Adds a comment to a public feature request.

Arguments:

feature_request_id (required): ID of the feature request to comment on.
content (required): Content of the comment.

Return Type: Returns a PublicFeatureRequestComment object representing the comment.

PublicFeatureRequestComment Fields

id (required): ID of the comment.
project_id (required): ID of the project the feature request belongs to.
feature_request_id (required): ID of the feature request the comment belongs to.
created_at (required): Date when the comment was created.
content (required): Content of the comment.
status (required): Status of the comment.
user_info (optional): User information related to the comment.
is_admin (optional): Boolean indicating if the commenter is an admin.

Example:

{
"mutation": "commentFeatureRequestPublic",
"variables": {
"feature_request_id": "feature123",
"content": "This is a great suggestion!"
}
}

proposeFeatureRequestPublic

Description: Proposes a public feature request by providing the title and summary.

Arguments:

title (required): Title of the feature request.
summary (optional): Summary of the feature request.

Return Type: Returns a PublicFeatureRequest object representing the proposed feature request.

PublicFeatureRequest Fields

id (required): ID of the feature request.
project_id (required): ID of the project the feature request belongs to.
created_at (required): Date when the feature request was created.
updated_at (required): Date when the feature request was last updated.
title (required): Title of the feature request.
summary (optional): Summary of the feature request.
user_info (optional): User information related to the feature request.
stats (required): Statistics related to the feature request.
comments (required): Comments made on the feature request.

Example:

{
"mutation": "proposeFeatureRequestPublic",
"variables": {
"title": "New Feature Request",
"summary": "This is a summary of the feature request."
}
}

deleteFeatureRequestComment

Description: Deletes a comment from a feature request.

Arguments:

project_id (required): ID of the project that the feature request belongs to.
feature_request_id (required): ID of the feature request that contains the comment.
feature_request_comment_id (required): ID of the comment to delete.

Return Type: Returns a FeatureRequest object.

The FeatureRequest object has the following fields:

id: ID of the feature request.
project_id: ID of the project that the feature request belongs to.
user_id: ID of the user who submitted the feature request.
issue_id: ID of the related issue.
title: Title of the feature request.
summary: Summary of the feature request.
labels: Array of label IDs associated with the feature request.
is_archived: Indicates whether the feature request is archived.
is_internal: Indicates whether the feature request is internal.
is_approved: Indicates whether the feature request is approved.

Example:

{
"mutation": "deleteFeatureRequestComment",
"variables": {
"project_id": "project123",
"feature_request_id": "feature123",
"feature_request_comment_id": "comment456"
}
}

Emails and Email Configuration

sendTestEmail

Description: Sends a test email for a specific post in a project.

Arguments:

project_id (required): ID of the project the post belongs to.
post_id (optional): ID of the post to send the test email for. If not provided, a test email will be sent for the project.

Return Type: Returns a Boolean value indicating whether the test email was sent successfully.

Example:

{
"mutation": "sendTestEmail",
"variables": {
"project_id": "project123",
"post_id": "post456"
}
}

saveEmailConfig

Description: Saves the email configuration for a project.

Arguments:

project_id (required): ID of the project to save the email configuration for.
send_day (required): Integer representing the day of the week to send emails (1 for Monday, 2 for Tuesday, etc.).
sending_interval (required): String representing the sending interval (e.g., "daily", "weekly", "monthly").
filter_labels (optional): Array of strings representing labels to filter posts.
include_labels (optional): Array of strings representing labels to include in posts.
include_segmented_posts (optional): Boolean indicating whether to include segmented posts.
post_content_type (optional): String representing the content type of the posts.
is_enabled (optional): Boolean indicating whether the email configuration is enabled.

Return Type:

project_id: ID of the project.
send_day: Integer representing the day of the week to send emails.
sending_interval: String representing the sending interval.
filter_labels: Array of strings representing labels to filter posts.
include_labels: Array of strings representing labels to include in posts.
include_segmented_posts: Boolean indicating whether to include segmented posts.
post_content_type: String representing the content type of the posts.
last_send_date: Date of the last email send.
is_enabled: Boolean indicating whether the email configuration is enabled.

Example:

{
"mutation": "saveEmailConfig",
"variables": {
"project_id": "project123",
"send_day": 2,
"sending_interval": "weekly",
"filter_labels": ["label1", "label2"],
"include_labels": ["label3", "label4"],
"include_segmented_posts": true,
"post_content_type": "html",
"is_enabled": true
}
}

saveProjectEmailSenderConfig

Description: Saves the email configuration for a project.

Arguments:

project_id (required): ID of the project to save the email configuration for.
send_day (required): Integer representing the day of the week to send emails (1 for Monday, 2 for Tuesday, etc.).
sending_interval (required): String representing the sending interval (e.g., "daily", "weekly", "monthly").
filter_labels (optional): Array of strings representing labels to filter posts.
include_labels (optional): Array of strings representing labels to include in posts.
include_segmented_posts (optional): Boolean indicating whether to include segmented posts.
post_content_type (optional): String representing the content type of the posts.
is_enabled (optional): Boolean indicating whether the email configuration is enabled.

Return Type:

project_id: ID of the project.
send_day: Integer representing the day of the week to send emails.
sending_interval: String representing the sending interval.
filter_labels: Array of strings representing labels to filter posts.
include_labels: Array of strings representing labels to include in posts.
include_segmented_posts: Boolean indicating whether to include segmented posts.
post_content_type: String representing the content type of the posts.
last_send_date: Date of the last email send.
is_enabled: Boolean indicating whether the email configuration is enabled.

Example:

Roadmap Configuration

saveProjectRoadmapConfig

Description: Saves the roadmap configuration for a project.

Arguments:

input (required): Object containing the input fields for saving the roadmap configuration.

The input object should have the following fields:

project_id (required): ID of the project to save the roadmap configuration for.
title (optional): Title of the roadmap.
is_enabled (required): Boolean indicating whether the roadmap is enabled.
is_hidden_in_feed (required): Boolean indicating whether the roadmap is hidden in the feed.
is_hidden_in_widget (required): Boolean indicating whether the roadmap is hidden in the widget.

Return Type: Returns the ProjectRoadmapConfig object.

The ProjectRoadmapConfig object has the following fields:

project_id: ID of the project.
title: Title of the roadmap.
is_enabled: Boolean indicating whether the roadmap is enabled.
is_hidden_in_feed: Boolean indicating whether the roadmap is hidden in the feed.
is_hidden_in_widget: Boolean indicating whether the roadmap is hidden in the widget.

Example:

{
"mutation": "saveProjectRoadmapConfig",
"variables": {
"input": {
"project_id": "project123",
"title": "Roadmap Title",
"is_enabled": true,
"is_hidden_in_feed": false,
"is_hidden_in_widget": true
}
}
}

Roadmap Status Management

saveStatus

Description: Saves or updates a status of a Roadmap Item.

Arguments:

project_id (required): ID of the project to save the status for.
status_id (optional): ID of the status. If provided, the status will be updated; otherwise, a new status will be created.
name (required): Name of the status.
color (required): Color of the status.

Return Type: Returns a Status object.

The Status object has the following fields:

id: ID of the status.
name: Name of the status.
color: Color of the status.

Example:

{
"mutation": "saveStatus",
"variables": {
"project_id": "project123",
"status_id": "status789",
"name": "In Progress",
"color": "#FFA500"
}
}

saveStatusOrder

Description: Saves the order of statuses in Roadmaps for a project.

Arguments:

project_id (required): ID of the project to save the status order for.
status_ids (required): Array of status IDs representing the order of statuses.

Return Type: Returns an array of Status objects in the specified order.

Example:

{
"mutation": "saveStatusOrder",
"variables": {
"project_id": "project123",
"status_ids": ["status1", "status2", "status3"]
}
}

deleteStatus

Description: Deletes a status from your Roadmap

Arguments:

project_id (required): ID of the project that the status belongs to.
status_id (required): ID of the status to be deleted.

Return Type: Returns a Result object.

The Result object has the following fields:

type: Type of the result (e.g., "success", "error").
message: Result message.

Example:

{
"mutation": "deleteStatus",
"variables": {
"project_id": "project123",
"status_id": "status456"
}
}

Issues Management

saveIssue

Description: Creates and saves an issue on the roadmap.

Arguments:

project_id (required): ID of the project to save the issue for.
issue_id (optional): ID of the issue. If provided, the existing issue will be updated.
user_id (optional): ID of the user assigned to the issue.
status_id (required): ID of the status for the issue.
title (required): Title of the issue.
summary (optional): Summary of the issue.
due_at (optional): Due date of the issue.
labels (optional): Array of label IDs associated with the issue.
sort_index (optional): Sort index of the issue. Default is 0.

Return Type: Returns the Issue object.

The Issue object has the following fields:

id: ID of the issue.
created_at: Date and time when the issue was created.
updated_at: Date and time when the issue was last updated.
status_id: ID of the status for the issue.
status: Status object containing information about the status.
title: Title of the issue.
summary: Summary of the issue.
due_at: Due date of the issue.
sort_index: Sort index of the issue.
user_id: ID of the user assigned to the issue.
user: User object containing information about the assigned user.
labels: Array of IssueLabel objects representing the labels associated with the issue.

mutation

{

saveIssue(project_id:12345,status_id:1234,title:"test") {

}

saveIssueOrder

Description: Saves the order of issues for a project.

Arguments:

project_id (required): ID of the project to save the issue order for.
issue_order_list (required): Array of IssueOrderInput objects representing the order of issues.

The IssueOrderInput object has the following fields:

issue_id (required): ID of the issue.
sort_index (required): Sort index of the issue.

Return Type: Returns a Result object.

The Result object has the following fields:

type: Type of the result (e.g., "success", "error").
message: Result message

mutation

{

saveIssueOrder(

project_id:29289

issue_order_list: [

{ id:"1234", sort_index:1234, status_id:"1234"

}

]

) {

message

}

deleteIssue

Description: Deletes an issue.

Arguments:

project_id (required): ID of the project that the issue belongs to.
issue_id (required): ID of the issue to be deleted.

Return Type: Returns a Boolean indicating whether the deletion was successful.

Example:

{
"mutation": "deleteIssue",

"variables": {
"project_id": "project123",
"issue_id": "issue456"
}
}

Notifications and Webhooks

saveNotification

Description: Saves a notification for a specific project and post.

Arguments:

project_id (required): ID of the project for which the notification is being saved.
post_id (required): ID of the post for which the notification is being saved.
interaction (required): Type of interaction triggering the notification.
type: Type of notification.
options: Additional options for the notification as a JSON object.
url: URL associated with the notification.

Return Type: Returns the saved notification.

Notification Fields:

id: ID of the notification.
project_id: ID of the associated project.
post_id: ID of the associated post.
options: Additional options for the notification as a JSON object.
interaction: Type of interaction triggering the notification.
type: Type of notification.
url: URL associated with the notification.

{
"mutation": "saveNotification",
"variables": {
"project_id": "project123",
"post_id": "post123",
"interaction": "like",
"type": "email",
"options": {},
"url": "https://example.com/notifications"
}
}

saveProjectWebhook

Description: Saves a webhook for a specific project.

Arguments:

project_id (required): ID of the project for which the webhook is being saved.
webhook_id: ID of the webhook (optional).
is_enabled (required): Boolean indicating whether the webhook is enabled.
url (required): URL associated with the webhook.

Return Type: Returns the saved project webhook.

ProjectWebhook Fields:

id: ID of the webhook.
project_id: ID of the associated project.
is_enabled: Boolean indicating whether the webhook is enabled.
url: URL associated with the webhook.

{
"mutation": "saveProjectWebhook",
"variables": {
"project_id": "project123",
"webhook_id": "webhook123",
"is_enabled": true,
"url": "https://example.com/webhook"
}
}

removeProjectWebhook

Description: Removes a webhook from a specific project.

Arguments:

project_id (required): ID of the project from which the webhook is being removed.
webhook_id (required): ID of the webhook to be removed.

Return Type: Returns the result of removing the project webhook.

Result Fields:

type: Result type indicating success or failure.
message: Result message providing additional information.

{
"mutation": "removeProjectWebhook",
"variables": {
"project_id": "project123",
"webhook_id": "webhook123"
}
}

Warnings and Activity

markWarningAsSeen

Description: Marks a warning as seen.

Arguments:

id (required): ID of the warning to mark as seen.
project_id (required): ID of the project.

Return Type: Returns a boolean indicating whether the operation was successful.

Example:

{
"mutation": "markWarningAsSeen",
"variables": {
"id": "warning123",
"project_id": "project123"
}
}

deleteActivity

Description: Deletes an activity.

Arguments:

project_id (required): ID of the project to delete the activity from.
id (required): ID of the activity to delete.

Return Type: Returns a boolean indicating whether the operation was successful.

Example:

{
"mutation": "deleteActivity",
"variables": {
"project_id": "project123",
"id": "activity123"
}
}