Create or update (upsert) a subscriber, send welcome, start a workflow

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.

In addition to sending welcome series, the more recent workflow feature is also available through this API. By specifying the workflow to start and any necessary arguments, it is possible to start a workflow after updating the subscriber. Note that if the conditions for starting the workflow are not met, the workflow is not executed for the subscriber.

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 format	JSON
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`.
workflow_kwargs optional	A dictionary of arguments to pass to the workflow being started.
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.