Create or Update Toll-Free Campaign | Pinnacle

import { PinnacleClient } from "rcs-js";
async function main() {
    const client = new PinnacleClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.campaigns.tollFree.upsert({
        brand: "b_1234567890",
        campaignId: "tf_1234567890",
        keywords: {
            help: {
                message: "Pinnacle Software Development Inc.: For assistance, visit https://pinnacle.sh/support or email founders@trypinnacle.app. Msg&data rates may apply. Reply STOP to cancel.",
            },
            optIn: {
                message: "Pinnacle Software Development Inc.: You're enrolled in account & security alerts. Msg&data rates may apply. Message frequency varies. Reply HELP for help, STOP to cancel. Terms: https://pinnacle.sh/terms/ Privacy: https://pinnacle.sh/privacy/",
                keywords: [
                    "START",
                    "SUBSCRIBE",
                ],
            },
        },
        links: {
            privacyPolicy: "https://www.pinnacle.sh/privacy",
            termsOfService: "https://www.pinnacle.sh/terms",
        },
        monthlyVolume: "10,000",
        name: "Pinnacle",
        optIn: {
            method: "PAPER",
            url: "https://www.pinnacle.sh/opt-in",
            workflowDescription: "End users opt-in when filling out the in-person intake forms where they will write their phone numbers and check a box indicating that they've opted in to messages. Link to paper form: https://www.pinnacle.sh/opt-in",
        },
        options: {
            ageGated: false,
        },
        productionMessageContent: "Hi [First Name], your order #[Order ID] has shipped and will arrive [Date]. Track here: [URL]. Reply HELP for help or STOP to unsubscribe.",
        useCase: {
            summary: "Customers who have opted into text messages can interact with our automated SMS chatbot to receive transaction-driven notifications (order status, shipping updates, account alerts), ask support questions, share photos with friends, and manage their account details via simple, conversational text flows. All messages are transactional or interactive flows customers opt into. Users can send images (e.g., receipts) and get guided replies.",
            value: "CHATBOT",
        },
    });
}
main();

{
  "brand": {
    "createdAt": "2024-08-17T08:00:30.632",
    "id": "b_1234567890",
    "isArchived": false,
    "status": "VERIFIED",
    "updatedAt": "2024-12-09T10:03:54.934",
    "address": "500 Folsom Street, San Francisco, CA 94105",
    "contact": {
      "email": "janedoe1@pinnacle.example",
      "name": "Jane Doe",
      "phone": "+14155550123",
      "title": "Customer Support Specialist"
    },
    "dba": "Pinnacle RCS",
    "ein": "12-3456789",
    "email": "founders@trypinnacle.app",
    "name": "Pinnacle",
    "sector": "TECHNOLOGY",
    "type": "PRIVATE_PROFIT",
    "website": "https://www.pinnacle.sh/"
  },
  "status": "VERIFIED",
  "campaignId": "tf_1234567890",
  "keywords": {
    "HELP": {
      "message": "Pinnacle Software Development Inc.: For assistance, visit https://pinnacle.sh/support or email founders@trypinnacle.app. Msg&data rates may apply. Reply STOP to cancel."
    },
    "OPT_IN": {
      "message": "Pinnacle Software Development Inc.: You're enrolled in account & security alerts. Msg&data rates may apply. Message frequency varies. Reply HELP for help, STOP to cancel. Terms: https://pinnacle.sh/terms/ Privacy: https://pinnacle.sh/privacy/",
      "keywords": [
        "START",
        "SUBSCRIBE"
      ]
    }
  },
  "links": {
    "privacyPolicy": "https://www.pinnacle.sh/privacy",
    "termsOfService": "https://www.pinnacle.sh/terms"
  },
  "monthlyVolume": "10,000",
  "name": "Pinnacle's Account Notifications",
  "optIn": {
    "method": "PAPER",
    "url": "https://www.pinnacle.sh/opt-in",
    "workflowDescription": "End users opt-in when filling out the in-person intake forms where they will write their phone numbers and check a box indicating that they've opted in to messages. Link to paper form: https://www.pinnacle.sh/opt-in"
  },
  "options": {
    "ageGated": false
  },
  "productionMessageContent": "• Hi [First Name], your order #[Order ID] has shipped and will arrive [Date]. Track here: [URL]. Reply HELP for help or STOP to unsubscribe.\n• Heads up! [Friend Name] shared 3 photos. Reply VIEW to see them. Reply HELP for help or STOP to unsubscribe.\n• Hello [First Name]! I'm Pinnacle's virtual assistant. How can I help you today? Ask about order status, account updates, photo sharing, or more. Reply HELP for assistance or STOP to unsubscribe.",
  "useCase": {
    "summary": "Customers who have opted into text messages can interact with our automated SMS chatbot to receive transaction-driven notifications (order status, shipping updates, account alerts), ask support questions, share photos with friends, and manage their account details via simple, conversational text flows. All messages are transactional or interactive flows customers opt into. Users can send images (e.g., receipts) and get guided replies.",
    "value": "CHATBOT"
  }
}

Create a new toll-free campaign or update an existing one.

To create a new campaign: Omit campaignId — one will be generated automatically.

Before you start: Create a brand first — you’ll need its id for the brand field.

All fields are required unless specified otherwise, and will be validated when submitted.

See the response for example values for each field.

Authentication

PINNACLE-API-KEYstring

API Key authentication via header

Request

This endpoint expects an object.

brandstringOptional

Brand id. This identifier is a string that always begins with the prefix b_, for example: b_1234567890.

campaignIdstringOptional

Unique identifier for the campaign. This identifier is a string that always begins with the prefix tf_, for example: tf_1234567890.

keywordsobjectOptional

Keyword response configuration.

linksobjectOptional

Legal documentation links.

monthlyVolumeenumOptional

Message volume.

namestringOptional

Display name of the campaign. This is not sent to carriers for approval and is only used for your reference on the Pinnacle dashboard.

optInobjectOptional

Opt-in method and workflow.

optionsobjectOptional

Campaign configuration options.

productionMessageContentstringOptional<=500 characters

Example message(s) that would be sent in production. Should reflect the actual content users will receive, including HELP/STOP disclosures. See the Production Message Content section for requirements.

useCaseobjectOptional

Use case classification for the campaign.

Response

Successfully created or updated toll-free campaign.

brandobject

Brand associated with this campaign.

statusenum

Current review status of the brand.

INCOMPLETE: Has not been submitted.
PENDING: Currently being reviewed.
VERIFIED: Verified and good to go.
VETTED: Brand has been vetted by an external provider and has received vetting scores.

Allowed values:

campaignIdstring

Unique identifier for the campaign. Begins with the prefix tf_.

keywordsobjectOptional

Keyword response configuration.

linksobjectOptional

Legal documentation links.

monthlyVolumeenumOptional

Message volume.

namestringOptional

Display name of the campaign.

optInobjectOptional

Opt-in keyword settings.

optionsobjectOptional

Campaign configuration options.

productionMessageContentstringOptional<=500 characters

Explain message that would be sent.

useCaseobjectOptional

Use case classification for the campaign.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error