Create/update (upsert) a subscriber and send welcome

Creates or updates a subscriber and sends a welcome message if the subscriber is new to the channel. New subscribers are subscribed to the channel. If the subscriber already exists and is unsubscribed, a 405 Method Not Allowed will returned. You must honor the users request to not recieve further messages. See Compliance documentation.

This function transactionally updates the subscriber, their tags and properties, and then sends a welcome. This means that any failure implies that the changes were not persisted and no message was sent.

This end point allows the updating of email_address,external_user_id, tags, and properties. Tags and properties specified for existing subscribers are merged. To replace the values, use the reset flag.

The welcome message can be specified in the request or a welcome series configured on the channel can be sent. It is an error to specify both a welcome message and request that a series be sent. It is also an error to request a welcome series when no series has been configured on the channel. Welcome series tagging is applied when determining which welcome series to send, which matches the subscriber's tags to some welcome series. If there is no matching series, the default series is sent.

A note on HTTP status codes that upsert can return

  • 200 We performed the updates on an existing subscriber
  • 201 We created a new subscriber and applied the updates
  • 400 Some part of your request was not in an acceptable form ( eg - you supplied an email address, but it was not in valid form )
  • 405 The subscriber has unsubscribed, and thus can not be re-added to the system via this call ( See Compliance documentation. )
  • 412 the phone number is not able to receive messages ( could be a landline )

Note: If are planning to make > 1000 calls to this end point in a single session, it would be better to use our enterprise bulk upsert end point. Please request access via support@chatitive.com.

Resource URL:

POST https://api.essential.to/v2/account/channels/{channel_sid}/subscribers/{phone_number}/upsert_and_welcome

Resource information:

Response formatJSON
Requires authentication?Yes

Parameters:

phone_number
required

The customer's phone number.

email_address
optional

The customer's email address.

external_user_id
optional

External ID for the customer.

properties
optional

Properties to set for the subscriber. An empty hash will clear the subscriber's properties.

tag_sids
optional

An array of Tag SIDs to add to the subscriber. An empty array will clear the subscriber's tags.

reset
optional

A boolean indicating that the subscriber's properties and tags should be cleared before applying the specified tags and properties.

welcome_message_body
optional

The welcome message text to send to the subscriber if they are new. This param is mutually exclusive with workflow_sid_to_start and send_welcome_series.

send_welcome_series
optional

A boolean indicating that a welcome series configured on the channel should be sent if the subscriber is new. This param is mutually exclusive with workflow_sid_to_start and welcome_message_body.

workflow_sid_to_start
optional

The SID for an automation workflow to start. The workflow must be enabled. If you are wanting to use it as a "welcome" automation, you should consider setting the max_subscriber_executions to 1. This param is mutually exclusive with send_welcome_series and welcome_message_body.

status
optional

The subscriber status - subscribed, unsubscribed, or unconfirmed. To add a user without subscribing them, include a status of "unconfirmed". If this param is not included, new users are subscribed to the channel. Please note, you can not change an unsubscribed subscriber's status with this mechanism. We generally assume that once a subscriber has said STOP, it should be respected. If you believe you have the legal right to re-subscribe them, use the update end point.

Sample code:

curl \
  -X POST \
  -u '[SID]:[TOKEN]' \
  -H 'Content-Type: application/json' \
  -d '{
    "email_address": "joe@example.com",
    "external_user_id": "12357111317",
    "properties": {
      "firstName": "Joe",
      "lastName": "Smith"
    },
    "tag_sids": ["p03Gjl8Uzn0RkZSpHXHnrw"],
    "send_welcome_series": true
  }' \
  'https://api.essential.to/v2/account/channels/p03Gjl8Uzn0RkZSpHXHnrw/subscribers/15009998080/upsert_and_welcome'

# Sample response
{
  "phone_number": "5009998080",
  "status": "subscribed",
  "subscribed_at": "2017-01-25T21:43:04.618Z",
  "unsubscribed_at": null,
  "created_at": "2017-01-25T21:43:04.620Z",
  "updated_at": "2017-01-25T21:43:04.620Z",
  "carrier": "AT&T Wireless",
  "carrier_updated_at": "2017-01-25T21:43:04.618Z",
  "added_to_inbox_at": null,
  "sid": "daBoeXvpfadRPgyYaaZJpw",
  "account_sid": "p03Gjl8Uzn0RkZSpHXHnrw",
  "channel_sid": "p03Gjl8Uzn0RkZSpHXHnrw",
  "transport_sid": "p03Gjl8Uzn0RkZSpHXHnrw"
}
Python coming soon.
Node coming soon.