Texa Desk Application API · Campaigns

Create a campaign

POST/api/v1/accounts/{account_id}/campaigns

Create a campaign. For a supported messaging inbox, provide scheduled_at to schedule a one-off campaign; omitting it makes the campaign eligible for the next scheduler run. Website campaigns use trigger_rules instead. Channel-specific campaign availability and requirements still apply. One-off campaigns require at least one audience label for delivery. WhatsApp campaigns also require template_params with the selected template name, language, and any variable values. A successful creation response does not confirm delivery. Requires an account administrator and API access enabled for the account.

Authorization

api_access_tokenheaderrequired

A person's access token (Texa Desk, Profile settings → Access token) or an agent bot's token, in the api_access_token header. It acts as that person, with their role's permissions.

Path parameters

account_idintegerrequired

The numeric ID of the account

Body application/json

campaignobjectrequired

Choose the variant matching the inbox referenced by inbox_id. The channel type is stored on the inbox and cannot be inferred from this request by a schema validator. These variants describe the inputs needed for delivery; creation can accept incomplete inputs without guaranteeing that the campaign will send.

campaign.titlestringrequired

Campaign title.

campaign.descriptionstring

Internal description of the campaign.

campaign.inbox_idintegerrequired

ID of an inbox in this account. Supported inbox types are Website, Twilio SMS, SMS, and WhatsApp.

campaign.sender_idinteger

ID of a user in this account to use as the campaign sender.

campaign.messagestringrequired

Campaign message content.

campaign.enabledboolean

Whether an ongoing website campaign is enabled. This does not cancel a scheduled one-off campaign.

campaign.scheduled_atstring (date-time)

Scheduled time for a one-off campaign, as an ISO 8601 timestamp with timezone. Defaults to the current time when omitted; website campaigns ignore this field. Responses return Unix seconds instead.

campaign.audiencearray of object

Required when creating a one-off SMS or WhatsApp campaign. Provide at least one label from this account. Contacts matching any selected label are included. When updating, omit this field to retain the existing audience.

campaign.audience[].typestringrequired

One of: Label.

campaign.audience[].idintegerrequired

ID of a label in this account.

campaign.trigger_rulesobject

Website campaign trigger rules. Defaults to an empty object and can be omitted for a one-off campaign.

campaign.trigger_only_during_business_hoursboolean

Restrict an ongoing website campaign to inbox business hours.

campaign.template_paramsobject

campaign.template_params.namestringrequired

Name of the approved template in the selected inbox's message_templates.

campaign.template_params.languagestringrequired

Language code matching that template in the selected inbox.

campaign.template_params.namespacestring

Template namespace, when present in the selected template.

campaign.template_params.categorystring

Category of the selected template.

campaign.template_params.processed_paramsobject

Values for the selected template's variables, grouped by component. Supply all parameters needed by that template. May be omitted for a template without variables. Body keys use positional numbers or the template's named parameters. Liquid expressions such as {{ contact.name }} are rendered separately for each recipient.

Responses

200

Success

idinteger

Account-scoped campaign ID. Use this value in campaign API paths.

titlestring

descriptionstring

account_idinteger

inboxobject

inbox.idnumber

ID of the inbox

inbox.namestring

The name of the inbox

inbox.website_urlstring

Website URL

inbox.page_idstring

Facebook Page ID associated with the inbox

inbox.instagram_idstring

Instagram account ID associated with the inbox

inbox.business_idstring

TikTok business ID associated with the inbox

inbox.provider_namestring

Provider username or page name associated with the social inbox

inbox.profile_idstring

X profile ID associated with the inbox

inbox.line_channel_idstring

LINE channel ID associated with the inbox

inbox.emailstring

Email address associated with the inbox

inbox.bot_namestring

Telegram bot name associated with the inbox

inbox.inbox_identifierstring

Public identifier associated with an API inbox

inbox.channel_typestring

The type of the inbox

inbox.avatar_urlstring

The avatar image of the inbox

inbox.widget_colorstring

Widget Color used for customization of the widget

inbox.website_tokenstring

Website Token

inbox.enable_auto_assignmentboolean

The flag which shows whether Auto Assignment is enabled or not

inbox.web_widget_scriptstring

Script used to load the website widget

inbox.welcome_titlestring

Welcome title to be displayed on the widget

inbox.welcome_taglinestring

Welcome tagline to be displayed on the widget

inbox.greeting_enabledboolean

The flag which shows whether greeting is enabled

inbox.greeting_messagestring

A greeting message when the user starts the conversation

inbox.channel_idnumber

ID of the channel this inbox belongs to

inbox.working_hours_enabledboolean

The flag which shows whether working hours feature is enabled

inbox.enable_email_collectboolean

The flag to enable collecting email from contacts

inbox.csat_survey_enabledboolean

The flag to enable CSAT survey

inbox.auto_assignment_configobject

Configuration settings for auto assignment

inbox.out_of_office_messagestring

Message to show when agents are out of office

inbox.working_hoursarray of object

Configuration for working hours of the inbox

inbox.working_hours[].day_of_weeknumber

Day of the week (0-6, where 0 is Sunday)

inbox.working_hours[].closed_all_dayboolean

Whether the inbox is closed for the entire day

inbox.working_hours[].open_hournumber

Hour when inbox opens (0-23)

inbox.working_hours[].open_minutesnumber

Minutes of the hour when inbox opens (0-59)

inbox.working_hours[].close_hournumber

Hour when inbox closes (0-23)

inbox.working_hours[].close_minutesnumber

Minutes of the hour when inbox closes (0-59)

inbox.working_hours[].open_all_dayboolean

Whether the inbox is open for the entire day

inbox.timezonestring

Timezone configuration for the inbox

inbox.callback_webhook_urlstring

Webhook URL for callbacks

inbox.allow_messages_after_resolvedboolean

Whether to allow messages after a conversation is resolved

inbox.lock_to_single_conversationboolean

Whether to lock a contact to a single conversation

inbox.sender_name_typestring

Type of sender name to display (e.g., friendly)

inbox.business_namestring

Business name associated with the inbox

inbox.branded_email_layoutstring

Liquid HTML layout for branded email replies. Available to administrators for Email inbox show/update responses.

inbox.hmac_mandatoryboolean

Whether HMAC verification is mandatory

inbox.selected_feature_flagsarray of string

Selected feature flags for the inbox

inbox.reply_timestring

Expected reply time

inbox.messaging_service_sidstring

Messaging service SID for SMS providers

inbox.phone_numberstring

Phone number associated with the inbox

inbox.mediumstring

Medium of communication (e.g., sms, email)

inbox.providerstring

Provider of the channel

senderobject

Sender details, or an empty object when no sender is assigned.

messagestring

template_paramsobject

campaign_statusstring

One of: active, processing, completed.

campaign_typestring

Derived from the inbox type; website campaigns are ongoing and supported messaging campaigns are one-off. One of: ongoing, one_off.

enabledboolean

scheduled_atinteger

Scheduled time in Unix seconds. Only present for one-off campaigns.

started_atinteger

Start time in Unix seconds. Only present for one-off campaigns.

completed_atinteger

Completion time in Unix seconds. Only present for one-off campaigns.

audiencearray of object

Audience for a one-off campaign. Only present for one-off campaigns.

trigger_rulesobject

trigger_only_during_business_hoursboolean

created_atstring (date-time)

updated_atstring (date-time)

401

Authentication failed or the user is not an account administrator

403

API access is disabled for the account

422

Campaign validation failed

curl -X POST 'https://desk.texadesk.com/api/v1/accounts/1/campaigns' \ -H "api_access_token: $TEXA_DESK_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "campaign": { "title": "January announcement", "inbox_id": 12, "message": "Our January offers are here!", "scheduled_at": "2027-01-15T10:00:00Z", "audience": [ { "type": "Label", "id": 5 } ] } }'

import os, requests headers = {"api_access_token": os.environ["TEXA_DESK_TOKEN"]} body = { "campaign": { "title": "January announcement", "inbox_id": 12, "message": "Our January offers are here!", "scheduled_at": "2027-01-15T10:00:00Z", "audience": [ { "type": "Label", "id": 5 } ] } } r = requests.post("https://desk.texadesk.com/api/v1/accounts/1/campaigns", headers=headers, json=body) r.raise_for_status() print(r.json())

{ "id": 1, "title": "string", "description": "string", "account_id": 1, "inbox": { "id": 1.0, "name": "string", "website_url": "string", "page_id": "string", "instagram_id": "string", "business_id": "string", "provider_name": "string", "profile_id": "string", "line_channel_id": "string", "email": "string", "bot_name": "string", "inbox_identifier": "string", "channel_type": "string", "avatar_url": "string", "widget_color": "string", "website_token": "string", "enable_auto_assignment": true, "web_widget_script": "string", "welcome_title": "string", "welcome_tagline": "string", "greeting_enabled": true, "greeting_message": "string", "channel_id": 1.0, "working_hours_enabled": true, "enable_email_collect": true, "csat_survey_enabled": true, "auto_assignment_config": {}, "out_of_office_message": "string", "working_hours": [ { "day_of_week": 1.0, "closed_all_day": true, "open_hour": 1.0, "open_minutes": 1.0, "close_hour": 1.0, "close_minutes": 1.0, "open_all_day": true } ], "timezone": "string", "callback_webhook_url": "string", "allow_messages_after_resolved": true, "lock_to_single_conversation": true, "sender_name_type": "string", "business_name": "string", "branded_email_layout": "string", "hmac_mandatory": true, "selected_feature_flags": [ "string" ], "reply_time": "string", "messaging_service_sid": "string", "phone_number": "string", "medium": "string", "provider": "string" }, "sender": {}, "message": "string", "template_params": {}, "campaign_status": "active", "campaign_type": "ongoing", "enabled": true, "scheduled_at": 1, "started_at": 1, "completed_at": 1, "audience": [ { "type": "string", "id": 1 } ], "trigger_rules": {}, "trigger_only_during_business_hours": true, "created_at": "2026-10-19T10:00:00Z", "updated_at": "2026-10-19T10:00:00Z" }