4.18j

TextMarks API V2 - AutoDoc: Anybody / invite_to_group()

Method: invite_to_group() (POST) - Invite a user to join (subscribe to) a TextMark group

Package: Anybody - Public data and methods for pre- or anonymous users (... View package)

Args:

Req? Name Type Description Test
REQ api_key API Key API Key (Register here)
REQ tm TextMark TextMark group to invite user to
REQ user User User account / phone# to invite
OPT name String Name provided by user (eg from form)
OPT email E-mail Email provided by user (eg from form)
OPT custom1 String Custom field (eg from form)
OPT prompt String Required: Prompt user agreed to when using the widget
OPT why String Required: Identifier indicating reason for this call (eg 'webform')
OPT details JSON Required: Details of the cause of this call (eg user IP addr, username, etc.)

Test:


Docs:

  • How it works:
    • The phone# specified receives a "Rply Y to join" type message and must reply Y within 24hr and before any other similar prompts (e.g. from other TextMarks).
    • Upon replying Y, the user becomes subscribed to the group and receives the applicable welcome message and disclosures.
    • If user does not reply, you must wait 24hr to send another request to that user for the same group while the current request is pending, else receive error #2041 (ERR_REQUEST_ALREADY_PENDING).
    • If the user is already a member of the group, receive error #2042 (ERR_REQUEST_ALREADY_DONE).
  • Development Tips:
    • During development, you may wish to clear a pending request by making another call to this method with a different keyword (which dislodges the previous pending request).
    • Receive system-level join/leave notifications by setting the "group_callback_url" in TextMarkManager.set_integration_config()
    • See also RegisteredUser.join_group() for subscribing an authenticated user without confirmation.
  • About the parameters:
    • The name, email, and custom1 fields are intended for use with forms where the user provides more than just their phone#. These fields are recorded on the user's account only for new users.
    • The prompt field contains the prompt that the user agreed to when using the widget.
    • The why and details parameters are used to log information of the root cause of this API call. TextMarks will audit your use of this API function from time to time and may terminate your account if erroneous or insufficient data is provided in these fields. These fields may also become required at some point in the near future, so you are strongly encouraged to start using them now.
      • why: Specify a token indicating the root cause. Some valid tokens are: webform
      • details: Specify a small JSON object with details of the cause. Keys expected: ipaddr (IP address of user who filled out form), email (e-mail address of user who filled out form), user (unique username or ID of user who filled out form), for (what purpose the program was advertised for, eg "upcoming concert announcements"), ...
  • Important Notes:
    • Important: You may only call this method when all of the following requirements are met:
      • A user typed their own phone# into a web form.
      • User checked a checkbox indicating agreement to our Terms of Service, or your own Terms of Service if such clearly indicate inclusion of TextMarks Terms.
      • User submitted the form no more than 5 minutes previously.
      • "Msg&Data Rates May Apply" or similar language next to phone# input box.
      • All other required disclosures and language are present.
    • Complaints related to improper use of this function will lead to termination of your account.

Resp:

JSON response.head.rescode==0 for success, or error code otherwise.
JSON-P callback: (as 'jsonp' param, optional) (blank for none)

HTTP:

POST https://api2ssl.textmarks.com//Anybody/invite_to_group/

More:

This page documents a single API function invite_to_group() within the Anybody package of the TextMarks Text Message API.
You may use the interactive form above to invoke this function and observe its actual JSON response.

More resources: