v1.0.0
OAS 3.1.0

OtterText

Welcome to the OtterText API Docs!

What is the OtterText API?

At OtterText, we envision a dynamic future for SMS, revolutionizing how businesses interact with their customers. Our mission is to provide a unified platform where every merchant can seamlessly connect with their customers through a single phone number, offering many engaging possibilities. From sending timely shipping updates and exclusive discount codes to exploring new, innovative use cases, the potential for meaningful communication is boundless. All these interactions should be housed within a unified conversation thread, akin to chatting with a close friend.

But to realize this ambitious vision, we understand the importance of collaboration with our valued partners. As much as we aspire to create the best, we acknowledge that we cannot do it alone. Thus, we invite our partners and retail shops to join us in building the future of SMS.

Enter the OtterText API: a gateway to limitless creativity and innovation. We are committed to continuously enriching this API with cutting-edge functionalities and powerful tools. These resources empower you to craft extraordinary applications on top of our platform, delivering enchanting SMS experiences to our collective customer base.

Key Features of the OtterText API:

  • Seamless Integration: The API provides straightforward integration with our platform, ensuring smooth communication and data exchange between your applications and OtterText.
  • Versatile Messaging: With our API, you can access a wide range of messaging capabilities. The possibilities are endless, whether you want to send transactional updates, promotional offers, or personalized messages.
  • Real-Time Insights: Leverage real-time data insights to understand customer behavior better, enabling you to tailor your SMS experiences for maximum impact.
  • Scalability and Reliability: Our API is designed to handle large-scale operations, ensuring your applications can scale effortlessly alongside your business growth.
  • Developer-Friendly Documentation: We provide comprehensive and user-friendly documentation, making it easy for developers of all levels to get started quickly and efficiently.
  • Secure and Privacy-Compliant: Security and privacy are at the core of our API. We take every measure to safeguard data and ensure compliance with industry standards.

Join us on this journey to redefine SMS interactions and unlock the potential of business-to-customer communications. Together, we can create a world where every merchant can provide personalized and engaging SMS experiences, building stronger relationships with their customers.

At OtterText, we are more than just an API provider; we are your partners in driving innovation, enabling growth, and delivering memorable SMS experiences that leave a lasting impact. Let's shape the future of SMS together.

Welcome to the OtterText API Docs!

Our API Docs are your gateway to building amazing experiences on top of the OtterText platform. Whether you're a seasoned developer or just starting your journey, we have the resources you need to get started.

Getting Started:

  • Authentication: Before you dive into the building with our API, you'll need to set up authentication. Learn how to access our platform and interact with your data securely.
  • API Reference: This comprehensive reference guide provides detailed information on all the endpoints and functionalities available through our API. Get familiar with the various methods to interact with your subscribers and messages.
  • Changelog: Stay up-to-date with the latest changes and updates to our API. We continuously strive to enhance our services, and the changelog keeps you informed about our improvements.

10DLC verification (SMS / MMS)

Before using endpoints that send or trigger SMS/MMS (for example Add Customer, Send Message, Schedule Message, Send Template, opt-in flows, and similar), your OtterText account must be 10DLC verified in the OtterText dashboard. If the account is not verified, the API typically returns HTTP 200 with a JSON body such as {"status":"error","message":"Action not allowed"} instead of sending the message. Email endpoints (for example Send Email) do not require 10DLC.

What's Next:

  • How to Add Subscribers Using the API: Learn how to add new subscribers to your OtterText account programmatically and seamlessly. This enables you to automate subscriber management and streamline your workflows.
  • Create Subscriber: Dive deeper into creating subscribers through the API. Master the parameters and options available to customize subscriber profiles according to your needs.
  • Rate Limits: Familiarize yourself with the rate limits imposed by our API. Understanding rate limits is essential to ensure smooth and efficient interactions with our platform.
  • Configuring Webhooks: Explore the power of webhooks and how to configure them to receive real-time updates from OtterText. Webhooks provide a reliable way to keep track of events and react accordingly.

We are excited to see the incredible applications and experiences you'll build using the OtterText API. Your creativity and innovation will play a crucial role in shaping the future of SMS interactions.

If you ever need assistance or have any questions while working with our API, our dedicated support team is here to help you every step of the way. Let's embark on this journey together and create something extraordinary!

Authentication

How to authenticate with our API

Technical Partners - Authorization and Authentication

To access the full power of the OtterText API, technical partners must use the appropriate authorization and authentication methods. Follow the guidelines below to obtain and use your private API key securely.

  1. Get Your Partner Keys: As a technical partner, you'll need to request your partner keys from the OtterText team. Please click here to request your API keys.
  2. Authorization Headers: When making requests related to your Triggers (e.g., getting, adding, updating, or deleting), no additional authorization is required.

Authorization/Authentication Process: Use your API Key in the bearer token header to authorize and authenticate a request. For example:

For partners, the token will be closer to:

Security Recommendations: To maintain a high level of security and prevent potential abuses, follow these best practices:

  • Avoid Exposing Private API Tokens: Never expose your private API tokens or shop tokens to the outside world, as this could lead to security vulnerabilities.
  • Avoid Calling API from Frontend Client: Do not make direct calls to the OtterText API from your frontend client (e.g., JavaScript included in your website code). Instead, consider using your backend API to communicate with our API securely.
  • Utilize Zapier or Backend Services: You can trigger API calls through services like Zapier or use your backend API to mediate requests to the OtterText API. This ensures that your private API tokens remain confidential and are not exposed client-side.

By adhering to these security practices, you can confidently build robust and secure integrations using the OtterText API. Our dedicated support team is always ready to help if you encounter any questions or need assistance. Let's create a secure and seamless SMS experience together!

TCPA Compliance - Building Trust and Transparency

At OtterText, we uphold compliance standards and foster trust between businesses and their customers. TCPA (Telephone Consumer Protection Act) compliance is paramount, and we take it seriously. As our valued partner, you must know the compliance requirements associated with using our API.

Confirmation Message for Opt-In Subscribers:

When using our API to add subscribers, all subscribers must confirm their opt-in to receive recurring automated messages. If subscribers do not provide confirmation, they will not be added to the Company's subscriber list.

Opt-in Message

[Company_Name]: Reply with your birthday YES to opt-in. Msg & data rates may apply. STOP to stop. HELP for assistance.

Opt-in Confirmation Message

You're now subscribed to [Company_Name] alerts. Msg&data rates may apply. Reply STOP to opt out—text HELP for more info.

S.H.A.F.T. Opt-in Message

[Company_Name]: Reply with your birthday MM/DD/YYYY to verify age & finish opt-in. Msg & data rates may apply. STOP to stop. HELP for assistance.

S.H.A.F.T. Opt-in Confirmation Message

Thank you for providing your birthday! We have verified your age and completed the opt-in process. Stay tuned for exciting updates and offers from [Company_Name]:.

S.H.A.F.T. Opt-in Message for Rewards

[Company_Name]: Thanks for your purchase! Reply with your Birthday MM/DD/YYYY to verify age & opt-in for rewards—text HELP for assistance. Reply STOP to cancel. Msg&data rates may apply..

*Please note that at present, this confirmation message is not customizable.

TCPA-Compliant Language in Subscriber Collection:

Wherever you collect a subscriber's phone number, whether, through a form or any other means, it is essential to include TCPA-compliant language to ensure transparency and inform subscribers of their rights.

Sample TCPA-compliant language:

By signing up, I agree to receive recurring automated marketing text messages (e.g., cart reminders, shipping notifications, two-way chat, marketing messages, etc) at the phone number provided. Consent is not a condition to purchase. Msg & data rates may apply. Msg frequency varies. Reply HELP for help and STOP to cancel. View our Terms of Service and Privacy Policy.

❗️Important:

Include links to the Terms and Conditions and Privacy Policy pages in the above message. These links are crucial in providing subscribers with additional information about their rights and data handling.

Text Message Compliance Guide:

For a comprehensive understanding of text message compliance best practices, we have prepared a helpful guide on Text Message Compliance. This guide offers insights and recommendations to ensure your SMS communications adhere to all relevant regulations and industry standards.

By strictly following TCPA compliance guidelines and ensuring transparency in subscriber interactions, you build trust with your customers and enhance the overall experience. Compliance protects your customers' privacy and helps you establish a long-lasting and positive relationship with them.

If you have any questions or require further assistance with compliance, our dedicated support team is here to provide guidance and support. Let's work together to create a compliant and trustworthy SMS experience for your audience.

Server:https://app.ottertext.com/api

Production

No authentication selected
Client Libraries
Shell Curl

AddCustomer

​

Customer will be matched based on the phone number provided. If customer not found then a new customer will be added and an Opt in message will be sent.

10DLC: Client must be 10DLC verified before SMS can be sent; otherwise you may receive Action not allowed.

Headers
  • Authorization
    Type: string
Body
application/json
Responses
  • application/json
Request Example for post/customers/add
curl https://app.ottertext.com/api/customers/add \
  --request POST \
  --header 'Authorization: Bearer {{BearerToken}}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'phone=+10000000000' \
  --form 'first_name=Test' \
  --form 'last_name=Test' \
  --form 'email=email@ottertext.com' \
  --form 'zip=00000' \
  --form 'partner=OtterText' \
  --form 'dob=mm/dd/yyyy' \
  --form 'verbalConsent=no' \
  --form 'tags=VIP, Gold, Returning'

{
  "status": "success",
  "message": "Customer added successfully"
}

OK

OptinOptout

​

Customer will be matched based on the phone number provided and will be opted in or opted out based on the parameters sent.

Headers
  • Authorization
    Type: string
Body
application/json
Responses
  • application/json
Request Example for post/customers/optinoptout
curl https://app.ottertext.com/api/customers/optinoptout \
  --request POST \
  --header 'Authorization: Bearer {{BearerToken}}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'phone=+10000000000' \
  --form 'sms=1' \
  --form 'email=1' \
  --form 'dob=mm/dd/yyyy' \
  --form 'partner=OtterText'

{
  "status": "success",
  "message": "Optin/Optout successful"
}

OK

OptinStatus

​

Customer will be matched based on the phone number provided and optinstatus will be returned response will have a customer object with optincheck

optincheck defination

1 = NewCustomer
2 = OptinRequested
3 = OptedIn
4 = OptedOut
5 = InvalidNumber

Query Parameters
  • phone
    Type: number

    Required: Customer Phone Number with country code

  • partner
    Type: string

    Required: Partner name using the API

Headers
  • Authorization
    Type: string
Responses
  • application/json
Request Example for get/customers/optinstatus
curl 'https://app.ottertext.com/api/customers/optinstatus?phone=%2B10000000000&partner=OtterText' \
  --header 'Authorization: Bearer {{BearerToken}}'

{
  "status": "success",
  "message": "Customer found",
  "customer": {
    "optincheck": "3"
  }
}

OK

UpdateCustomer

​

Customer will be matched based on the phone number provided and customer information will be updated. Note: Phone number will not be updated it will only be used to match the customer record from our database

Headers
  • Authorization
    Type: string
Body
application/json
Responses
  • application/json
Request Example for post/customers/update
curl https://app.ottertext.com/api/customers/update \
  --request POST \
  --header 'Authorization: Bearer {{BearerToken}}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'phone=+10000000000' \
  --form 'first_name=Ben' \
  --form 'last_name=Nelson' \
  --form 'email=email@ottertext.com' \
  --form 'zip=00000' \
  --form 'partner=OtterText'

{
  "status": "success",
  "data": "Customer updated successfully"
}

OK

SendMessage

​

Send SMS or MMS immediately. Same endpoint is used for SMS and MMS based on parameter values (sms_or_mms, message / messagemms, image). Set send_type to 1 for instant delivery.

10DLC: Client must be 10DLC verified; otherwise the API may return {"status":"error","message":"Action not allowed"} and the message will not be sent.

Headers
  • Authorization
    Type: string
Body
required
application/json
Responses
  • application/json
Request Example for post/customers/sendmessage
curl https://app.ottertext.com/api/customers/sendmessage \
  --request POST \
  --header 'Authorization: Bearer {{BearerToken}}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'customer=+10000000000' \
  --form 'first_name=Test' \
  --form 'last_name=Test' \
  --form 'sms_or_mms=1' \
  --form 'message=Test' \
  --form 'send_type=1' \
  --form 'partner=OtterText' \
  --form 'sendThisMessageAndDelayOptin=false'

{
  "status": "success",
  "message": "Message Sent Successfully"
}

OK

ScheduleMessage

​

Schedule SMS or MMS for later delivery. Set send_type to 2 and provide scheduled_date_time. Same handler as SendMessage; matches the Postman ScheduleMessage request.

10DLC: Client must be 10DLC verified; otherwise the API may return {"status":"error","message":"Action not allowed"} and the message will not be scheduled.

Headers
  • Authorization
    Type: string
Body
required
application/json
Responses
  • application/json
Request Example for post/customers/sendmessage/schedule
curl https://app.ottertext.com/api/customers/sendmessage/schedule \
  --request POST \
  --header 'Authorization: Bearer {{BearerToken}}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'customer=+10000000000' \
  --form 'first_name=First' \
  --form 'last_name=Last' \
  --form 'sms_or_mms=1' \
  --form 'message=Test' \
  --form 'send_type=2' \
  --form 'scheduled_date_time=Mon Aug 07 2023 12:04:53 GMT+0500' \
  --form 'partner=OtterText' \
  --form 'sendThisMessageAndDelayOptin=false'

{
  "status": "success",
  "message": "Message Sent Successfully"
}

OK

SendTemplate

​

Send a pre-built template to a customer. List available templates from the Templates endpoint; use the id from that response as template_id. Matches the Postman SendTemplate request.

10DLC: Client must be 10DLC verified; otherwise the API may return {"status":"error","message":"Action not allowed"} and the template message will not be sent.

Headers
  • Authorization
    Type: string
Body
required
application/json
Responses
  • application/json
Request Example for post/customers/sendmessage/template
curl https://app.ottertext.com/api/customers/sendmessage/template \
  --request POST \
  --header 'Authorization: Bearer {{BearerToken}}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'customer=+10000000000' \
  --form 'sms_or_mms=1' \
  --form 'send_type=1' \
  --form 'partner=OtterText' \
  --form 'template_id=1'

{
  "status": "success",
  "message": "Message Sent Successfully"
}

OK

Webhook

​

Subscribe to webhook for different triggers. Same endpoint will be used to add and Update a webhook URL. If same URL is provided then settings will be updated for the existing Webhook else new webhook will be added.

If action_form_submitted is set to true. Whenever a customer submits a form on the website Optin Page or website chat. The customer information object will be sent to the webhook URL provided. Following is a sample webhook data

{

"first_name": "Nick",

"last_name": "Adams",

"dob": "1990-06-22",

"email": "customer@ottertext.com",

"zip": "00000",

"phone": "+10000000000",

"company": "Example Company"

}

If action_message_received is set to true. Whenever a new message is received from an opted in customer or a new customer the customer phone number and text message will be sent to the webhook URL provided. Following is a sample webhook data

{

"CustomerPhoneNumber": "+10000000000",

"Message": "Sample test message"

}

Headers
  • Authorization
    Type: string
Body
application/json
Responses
  • application/json
Request Example for post/clients/webhook
curl https://app.ottertext.com/api/clients/webhook \
  --request POST \
  --header 'Authorization: Bearer {{BearerToken}}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'webhook=https://app.ottertext.com' \
  --form 'partner=OtterText' \
  --form 'status=1' \
  --form 'action_form_submitted=1' \
  --form 'action_message_received=1'

{
  "status": "success",
  "message": "Webhook added successfully"
}

OK

Templates

​

Get a list of predefined templates. These templates can be used with the SendTemplate API to send a predefined templated message to a customer. The id returned in response corresponds to the template_id in SendTemplate endpoint

Headers
  • Authorization
    Type: string
Body
application/json
Responses
  • application/json
Request Example for post/clients/templates
curl https://app.ottertext.com/api/clients/templates \
  --request POST \
  --header 'Authorization: Bearer {{BearerToken}}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'draw=1' \
  --form 'start=0' \
  --form 'length=10'

{
  "status": "success",
  "data": {
    "draw": "1",
    "recordsTotal": 1,
    "recordsFiltered": 1,
    "data": [
      {
        "id": 1,
        "title": "Gun is ready",
        "message": "Hi {{first_name}}, Your gun is ready for pickup during business hours.",
        "client_id": 2,
        "status": "Active",
        "created_at": "2023-01-23 12:04:51",
        "updated_at": "2023-01-23 12:04:51"
      }
    ]
  }
}

OK

SendEmail

​
Headers
  • Authorization
    Type: string
Body
application/json
Empty object
Responses
  • text/plain
Request Example for post/email/send
curl https://app.ottertext.com/api/email/send \
  --request POST \
  --header 'Authorization: Bearer {{BearerToken}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "to": "recipient@example.com",
  "from": "sender@example.com",
  "from_name": "John Doe",
  "reply_to": "noreply@example.com",
  "subject": "Test Email Subject",
  "body": "Hello, this is a test email body.",
  "cc": [
    "ccperson1@example.com",
    "ccperson2@example.com"
  ],
  "bcc": [
    "hidden1@example.com",
    "hidden2@example.com"
  ],
  "attachments": [
    "https://example.com/files/invoice.pdf",
    "https://example.com/files/contract.docx"
  ]
}'

{
  "status": "success",
  "message": "Email sent successfully"
}

OK

Models