NagentArtefacts
Dev & Technology
Enterprise and White Glove
Company
Toneden connects to a Nagent workspace with an API key. Once it is connected, agents can call 26 Toneden actions, such as "Create Advertising Campaign", "Create Attachment" and "Create ToneDen Link". Nothing is enabled on connect: each action is allowed one at a time, and an action with side effects runs or waits for a person according to the agent's level.
Every operation an agent can call against Toneden, with input parameters and output schema.
TONEDEN_CREATE_ADVERTISING_CAMPAIGNTool to create a ToneDen advertising campaign on Facebook or Google platforms. Use when you need to launch a new ad campaign with specified budget, targeting, and creatives.
Input parameters
Campaign name/title for identification.
Initial campaign status (e.g., draft, active, paused).
URL or object ID to promote.
Currency code for the budget (e.g., USD, EUR).
The advertising platform to use (facebook or google).
Array of audience objects for targeting. Structure varies by platform.
Creative assets for the campaign. Structure varies by platform.
Marketing objective for the campaign.
Additional targeting parameters for the campaign.
Budget allocation strategy (daily or lifetime).
Campaign objective type (e.g., conversions, reach, engagement).
Numeric budget value in the specified currency.
UNIX timestamp for when the campaign should end.
If true, the campaign runs indefinitely (no end date).
Email addresses to receive campaign reports.
Optimization goal identifier for the campaign.
UNIX timestamp for when the campaign should start.
URL to direct users to when they click the ad.
ID of the external poster/page for the campaign.
Instagram account ID for Instagram placements (Facebook platform).
ID of the external ad account on the platform.
If true, disables all email notifications for this campaign.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_CREATE_ATTACHMENTTool to create an attachment. Use when you need to programmatically create a social unlock or contest attachment after gathering all required parameters.
Input parameters
Attachment type: 'unlock' for social unlock or 'contest' for a contest attachment.
Social action for single-action attachments. Required when type='unlock' and only one social action.
List of social actions for multi-action attachments. Required when type='contest' or multiple unlock actions.
Coupon code text to display. Required when unlock_type='coupon'.
Reward type for social unlocks. Required when type='unlock'.
URL of the file to download or link target. Required when unlock_type='download' or 'link'.
Facebook Page ID to subscribe on Messenger. Required when platform='facebook-messenger'.
URL of the unlisted video to stream. Required when unlock_type='stream'.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_CREATE_LINKTool to create a ToneDen link. Use when you have the target_type and, if needed, the services array. Supports creation of links for music, podcast, livestream, event, tour, biglink, fundraiser, smartlink, and custom types.
Input parameters
Conditionally required array of service-specific objects; required for target_types: music, podcast, livestream, tour, biglink; must be omitted for event, fundraiser, smartlink, custom.
Determines the link landing page type.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_DELETE_ADVERTISING_CAMPAIGNDeletes a ToneDen advertising campaign by ID using DELETE /advertising/campaigns/{campaignID}.
Input parameters
ID of the advertising campaign to delete. Accepts string or int.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_DELETE_LINKDeletes a ToneDen link by ID using DELETE /links/{linkID}.
Input parameters
ID of the link to delete. Accepts string or int.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_DELETE_PLAYBOOK_CAMPAIGNDeletes a ToneDen playbook campaign by ID using DELETE /playbooks/campaigns/{campaignID}.
Input parameters
ID of the playbook campaign to delete. Accepts string or int.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_EXPAND_LINK_TEMPLATETool to expand a ToneDen link template. Use when you need to retrieve the full template link with your tracking pixels and optional service links. Provide a URL to generate platform services for music or podcast content.
Input parameters
Optional source URL for music or podcast; when provided, the API generates a services array linking to that track across platforms.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_GET_ADVERTISING_CAMPAIGNRetrieve a specific advertising campaign by its ID using ToneDen's API. Endpoint: GET /advertising/campaigns/{campaignID} Notes: - This endpoint does not require a userID in the path per official docs. - Some accounts may not have advertising access; in such cases, non-2xx responses are still returned here for observability instead of raising, so the caller can inspect the error object.
Input parameters
The ID of the advertising campaign to retrieve.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_GET_ADVERTISING_CAMPAIGN_CREATIVE_INSIGHTSRetrieve creative performance insights for a specific advertising campaign using ToneDen's API. Endpoint: GET /advertising/campaigns/{campaignID}/creativeInsights. Note: Endpoint uses camelCase `creativeInsights` per official docs.
Input parameters
The ID of the advertising campaign to retrieve creative insights for.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_GET_ADVERTISING_CAMPAIGN_INSIGHTSRetrieve performance insights for a specific advertising campaign using ToneDen's API. Endpoint: GET /advertising/campaigns/{campaignID}/insights.
Input parameters
The ID of the advertising campaign to retrieve insights for.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_GET_ATTACHMENTTool to retrieve an attachment by ID. Use when you need to fetch details of an existing attachment by its ID.
Input parameters
The unique identifier of the attachment to retrieve.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_GET_ATTACHMENT_ENTRIES_TIME_SERIESTool to fetch time-series entry statistics for a specific attachment. Use when you need chronological entry data points for an attachment.
Input parameters
The unique identifier of the attachment for which to retrieve entry time-series data.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_GET_ATTACHMENT_ENTRIES_TOTALSTool to fetch summary counts of entries for an attachment. Use when you need aggregate entry counts over day, week, month, and lifetime.
Input parameters
The unique identifier of the attachment for which to retrieve entry totals.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_GET_ATTACHMENT_UNLOCKS_BY_PLATFORMTool to fetch counts of unlocks by platform for a specific attachment. Use when you need a breakdown of unlocks across platforms like Spotify, Twitter, etc.
Input parameters
The unique identifier of the attachment for which to retrieve unlock counts by platform.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_GET_ATTACHMENT_UNLOCKS_TIME_SERIESTool to fetch time-series unlock statistics for a specific attachment. Use when you need chronological unlock data points for an attachment.
Input parameters
The unique identifier of the attachment for which to retrieve unlock time-series data.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_GET_LINKTool to retrieve a specific ToneDen link by its ID. Use when you need to fetch details about an existing link.
Input parameters
Numeric ID of the link to retrieve.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_GET_LINK_INSIGHTSTool to retrieve detailed insights for a ToneDen link. Use when you have a link ID and need metrics such as clicks, clickthroughs, email clicks, etc.
Input parameters
Numeric ID of the link to retrieve performance data for.
Which action type to query results for. 'rsvps' is only a valid value for livestream links.
If provided, only actions that occurred before the specified date will be counted. Should be in ISO 8601 format.
If provided, only actions that occurred after the specified date will be counted. Should be in ISO 8601 format.
Groups results by visitor location.
If true, only one action per fan will be counted in the stats.
Groups results by specified time interval.
Groups results by service clicked.
Groups results by referring domain.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_GET_LINK_INSIGHTS_OVERVIEWTool to retrieve a summary overview of a link's performance insights. Use when you have a link ID and need aggregated metrics across platforms.
Input parameters
The unique identifier of the link to retrieve insights for.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_GET_USERTool to retrieve a specific ToneDen user by ID. Use when you need to fetch user profile information or details about the currently authenticated user.
Input parameters
ID of the user to retrieve. Use 'me' to get the currently-authenticated user, or provide a numeric user ID.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_LIST_PLAYBOOK_CAMPAIGNSTool to list playbook campaigns. Use when you need to retrieve a paginated list of all playbook campaigns.
Input parameters
Maximum number of campaigns to return; must be >= 1.
Number of campaigns to skip before starting to collect the result set; must be >= 0.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_LIST_USER_ATTACHMENTSTool to list attachments for a user. Use when you need to retrieve social unlocks or contest attachments belonging to a specific user.
Input parameters
Type of attachments to list: 'unlock' for social unlocks or 'contest' for contests.
Maximum number of results to return.
Pagination offset for results.
Numeric ID of the user whose attachments to list.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_LIST_USER_LISTSTool to retrieve a list of a user's advertising user lists. Use when you need to fetch all user lists (custom audiences) for a specific ToneDen user.
Input parameters
ID of the user whose user lists to retrieve. Use 'me' to get lists for the currently-authenticated user, or provide a numeric user ID.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_UPDATE_ATTACHMENTTool to update an existing attachment. Use when you need to flexibly modify any attachment field (or add custom fields) after its creation.
Input parameters
Attachment type: 'unlock' for social unlock or 'contest' for multi-action contest
Additional arbitrary fields to merge into the update payload
Social action for single-action attachments. Required when type='unlock'
Custom path segment for the attachment's landing page
List of social actions for multi-action attachments. Required when type='contest'
Coupon code text when unlock_type is 'coupon'
Type of unlock for social unlock attachments
ID of the attachment to update
URL for download or link when unlock_type is 'download' or 'link'
Facebook Page ID for Messenger subscriptions when platform='facebook-messenger'
Streaming URL when unlock_type is 'stream'
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_UPDATE_PLAYBOOK_CAMPAIGNUpdates a ToneDen playbook campaign by ID using PUT /playbooks/campaigns/{campaignID}. Note: ToneDen's public docs do not expose the full request body schema for updates. This action sends a flexible JSON payload composed from provided fields and returns diagnostic information without raising on non-2xx responses, to aid real-world testing.
Input parameters
Name of the playbook campaign
Optional notes or description for the campaign
Optional budget value for the campaign
Status of the campaign (if supported by API)
Additional arbitrary fields for the update payload when not covered by explicit parameters
ISO8601 end date string (if supported by API)
Arbitrary metadata dictionary to include in the update
ISO8601 start date string (if supported by API)
ID of the playbook campaign to update. Accepts string or int.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_UPDATE_USERTool to update a ToneDen user's profile. Use when you need to modify user details (e.g., name, location, or settings) after fetching them.
Input parameters
City where the user is located
Bio or about text for the user
State or province of the user
Custom policy text for the user
Country code (e.g., 'US')
ID of the user to update; use 'me' to target the current authenticated user
URL to the user's public profile page
New display name for the user
IANA timezone string (e.g., 'America/Los_Angeles')
List of additional email addresses for the user
User interface preference settings
User advertising preference settings
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TONEDEN_VALIDATE_LINK_PATHTool to check if a link path/subdomain combination is unique and valid. Use when creating or editing a ToneDen link to verify the path is available.
Input parameters
The shortened_path to check for validity.
Numeric ID of the link being checked for validity. This parameter can be passed when editing a link to prevent the uniqueness check from comparing the link to itself.
The subdomain to check for validity.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
Agents can call 26 Toneden actions on Nagent, including "Create Advertising Campaign", "Create Attachment" and "Create ToneDen Link". Create Advertising Campaign: Create a ToneDen advertising campaign on Facebook or Google platforms. Each action is listed on this page with its input parameters and its output.
Toneden connects with an API key, under your workspace's own connection. Nothing is enabled on connect: each action is allowed one at a time and can be scoped to the agents that need it.
Create Advertising Campaign takes 6 required inputs: platform, audiences, creatives, budget_type, budget_amount and external_ad_account_id. It also takes 16 optional inputs: title, status, target, currency, objective, targeting, target_type, end_timestamp, is_continuous, report_emails, optimization_id, start_timestamp, target_link_url, external_poster_id, instagram_account_id and disable_all_notifications. It returns data, error and successful.