Create Project

Create a new project. type selects the payload shape: broadcast (the default) sends one message to the audience; survey runs a multi-question flow with branching.

Phone numbers. Assign one or more sending numbers via phone_number_ids (up to 49). The project spreads new conversations randomly across the assigned numbers, and once a recipient has been messaged from a given number every later message to that recipient comes from the same number (sticky sender). A single legacy phone_number_id is still accepted and is treated as a one-element phone_number_ids.

Channel. channel defaults to 10dlc. For broadcast projects a 10dlc channel requires brand_id + campaign_id (and toll_free_verification_id must be omitted), while toll-free requires toll_free_verification_id with matching toll-free phone_number_ids (brand_id/campaign_id omitted). Survey projects always require campaign_id, on both channels.

Surveys. questions defines the whole flow: an intro at sequence 1, then multiple_choice/open_ended questions, optionally ending with an outro. Multiple-choice options can branch with next_sequence, and no_match_sequence routes unmatched replies; both are forward-only. Each question can be SMS or MMS (message_type + media_ids). Question text supports merge tags and {tracking_url}. Surveys need at least 2 questions and 1 phone number.

When link_tracking_enabled is true, link_tracking_destination_url and link_tracking_domain_id become required. The destination URL may embed the selected link_tracking_param_field anywhere via a placeholder named after it, e.g. https://test.com?utm_content=xyzd_{linkid} redirects as ...utm_content=xyzd_ABC123 (no separate &linkid= pair is appended). Without a placeholder the field is appended as its own query pair. link_tracking_destination_url may also be exactly https://{<link_tracking_param_field>}, e.g. https://{custom_url}; each recipient’s tracking link then redirects to the URL stored in that contact field instead (short_id is still appended as a query param, but no <field> query param is). In this mode link_tracking_fallback_url is required, and recipients whose field is empty or not a valid URL go there instead. phone cannot be used as a whole-URL destination, and a {field} token in the host position must be the entire URL (https://{custom_url}/path is rejected). A placeholder that does not match the selected field, or an invalid whole-URL form, is rejected with a 400 (INVALID_LINK_PLACEHOLDER).

Opt-out footer. Broadcast messages automatically carry the STOP=END opt-out footer. Set opt_out_footer_enabled to false to disable it (defaults to true); surveys never carry the footer.

Drafts. contact_list_ids is optional. With at least one list the created project starts in awaiting_test status (send a test, then schedule). Without it the project is created as a draft; attach lists later via PATCH /projects/{id} and the project moves to awaiting_test automatically. Drafts cannot be tested or scheduled. The response’s completeness block shows what is still missing.