messenger_bot

v1.0.0-beta10

messenger_bot v1.0.0-beta10 MessengerBot

MessengerBot Client

Link to this section Summary

Types

app_id()

Facebook App ID

cursor()

Pagination cursor value from previous calls, can be nil

domains()

Domain list

fields()

Field list

label_id()

Custom label ID

metrics()

Metric list

page_id()

Facebook Page ID

page_ref()

Reference for Facebook Page data

psid()

User’s page-scoped ID or app-scoped ID

res()

API call execution result

tx_id()

Optional request transaction identifier. This value is passed is passed into EventBus Event struct

Functions

broadcast_message(arg, message_ref, tx_id \\ nil)

Broadcast API / broadcast_message

create_custom_label(arg, label, tx_id \\ nil)

Broadcast API / custom_labels

create_message_creative(arg, messages, tx_id \\ nil)

Broadcast API / create_message_creatives

create_messenger_code(arg, req, tx_id \\ nil)

Messenger Code API

delete_custom_label(arg, label_id, tx_id \\ nil)

Broadcast API / delete_custom_label

fetch_account_linking_url(arg, tx_id \\ nil)

Messenger Profile API / Fetch account linking url

fetch_custom_label(arg1, arg2, tx_id \\ nil)

Broadcast API / fetch_custom_label

fetch_get_started(arg, tx_id \\ nil)

Messenger Profile API / Fetch get started

fetch_greeting(arg, tx_id \\ nil)

Messenger Profile API / Fetch greeting

fetch_home_url(arg, tx_id \\ nil)

Messenger Profile API / Fetch home url

fetch_ids_for_app(arg1, arg2, tx_id \\ nil)

ID Matching API / ids_for_app

fetch_ids_for_page(arg1, arg2, tx_id \\ nil)

ID Matching API / ids_for_page

fetch_insights(arg1, arg2, tx_id \\ nil)

Insights API

fetch_messaging_feature_review(arg, tx_id \\ nil)

Messaging Feature Review API

fetch_payment_settings(arg, tx_id \\ nil)

Messenger Profile API / Fetch payment settings

fetch_persistent_menu(arg, tx_id \\ nil)

Messenger Profile API / Fetch persistent menu

fetch_secondary_receivers(arg, fields, tx_id \\ nil)

Handover Protocol API / secondary_receivers

fetch_target_audience(arg, tx_id \\ nil)

Messenger Profile API / Fetch target audience

fetch_user_profile(arg1, arg2, tx_id \\ nil)

User Profile API / user_profiles

fetch_whitelisted_domains(arg, tx_id \\ nil)

Messenger Profile API / Fetch whitelisted domains

label_user(arg1, arg2, tx_id \\ nil)

Broadcast API / label_user

list_custom_labels(arg1, arg2, tx_id \\ nil)

Broadcast API / list_custom_labels

list_custom_labels_of_user(arg1, arg2, tx_id \\ nil)

Broadcast API / list_custom_labels_of_user

pass_thread_control(arg, req, tx_id \\ nil)

Handover Protocol API / pass_thread_control

request_thread_control(arg, req, tx_id \\ nil)

Handover Protocol API / request_thread_control

reset_account_linking_url(arg, tx_id \\ nil)

Messenger Profile API / Reset account linking url

reset_get_started(arg, tx_id \\ nil)

Messenger Profile API / Reset get started

reset_greeting(arg, tx_id \\ nil)

Messenger Profile API / Reset greeting

reset_home_url(arg, tx_id \\ nil)

Messenger Profile API / Reset home url

reset_payment_settings(arg, tx_id \\ nil)

Messenger Profile API / Reset payment settings

reset_persistent_menu(arg, tx_id \\ nil)

Messenger Profile API / Reset persistent menu

reset_target_audience(arg, tx_id \\ nil)

Messenger Profile API / Reset target audience

reset_whitelisted_domains(arg, tx_id \\ nil)

Messenger Profile API / Reset whitelisted domains

send_message(arg, req, tx_id \\ nil)

Send API

set_account_linking_url(arg, account_linking_url, tx_id \\ nil)

Messenger Profile API / Set account linking url

set_get_started(arg, payload \\ "GET_STARTED", tx_id \\ nil)

Messenger Profile API / Set get started

set_greeting(arg, greeting, tx_id \\ nil)

Messenger Profile API / Set greeting

set_home_url(arg, home_url, tx_id \\ nil)

Messenger Profile API / Set home url

set_payment_settings(arg, payment_settings, tx_id \\ nil)

Messenger Profile API / Set payment_settings

set_persistent_menu(arg, persistent_menu, tx_id \\ nil)

Messenger Profile API / Set persistent menu

set_target_audience(arg, target_audience, tx_id \\ nil)

Messenger Profile API / Set target audience

set_whitelisted_domains(arg, whitelisted_domains, tx_id \\ nil)

Messenger Profile API / Set whitelisted domains

take_thread_control(arg, req, tx_id \\ nil)

Handover Protocol API / take_thread_control

unlabel_user(arg1, arg2, tx_id \\ nil)

Broadcast API / unlabel_user

unlink_account(arg, req, tx_id \\ nil)

Account Linking API / unlink_accounts

upload_attachment(arg, attachment, tx_id \\ nil)

Attachment Upload API

Link to this section Types

Link to this type app_id() 
app_id() :: String.t()

Facebook App ID

Link to this type cursor() 
cursor() :: {:after, String.t()} | {:before, String.t()} | {}

Pagination cursor value from previous calls, can be nil

Link to this type domains() 
domains() :: [String.t()]

Domain list

Link to this type fields() 
fields() :: [String.t()]

Field list

Link to this type label_id() 
label_id() :: integer() | String.t()

Custom label ID

Link to this type metrics() 
metrics() :: [String.t()]

Metric list

Link to this type page_id() 
page_id() :: String.t()

Facebook Page ID

Link to this type page_ref() 
page_ref() :: {app_id(), page_id()}

Reference for Facebook Page data

Using page_ref, MessengerBot client access to the page token and app secret data from the configuration.

Link to this type psid() 
psid() :: integer() | String.t()

User’s page-scoped ID or app-scoped ID

Link to this type res() 
res() :: {:ok, Map.t()} | {:error, Map.t()}

API call execution result

Successful HTTP requests will return tuple of :ok with response body as Map. Unsuccessful HTTP requests will return tuple of :error with response body as Map.

For HTTP client errors, it will return tuple of {:error, %{error: reason}}, where reason is an error tuple of Tesla dependency.

Link to this type tx_id() 
tx_id() :: String.t()

Optional request transaction identifier. This value is passed is passed into EventBus Event struct.

It is usually used to track events in the same transaction. For example; when you send batch messages to an audience, you can track which messages delivered in the same transaction. Or while setting a Messenger Profile, you may need to make series of requests to complete the page setup. You can use same tx_id to trace sequential related events.

Link to this section Functions

Link to this function broadcast_message(arg, message_ref, tx_id \\ nil) 
broadcast_message(page_ref(), Map.t(), tx_id()) :: res()

Broadcast API / broadcast_message

Examples 

iex> message_ref = %{message_creative_id: 938461089}
iex> MessengerBot.broadcast_message({"<AppID>", "<PageID>"}, message_ref)
{:ok, %{"broadcast_id" => 827}}
Link to this function create_custom_label(arg, label, tx_id \\ nil) 
create_custom_label(page_ref(), Map.t(), tx_id()) :: res()

Broadcast API / custom_labels

Examples 

iex> label = %{name: "<LABEL_NAME>"}
iex> MessengerBot.create_custom_label({"<AppID>", "<PageID>"}, label)
{:ok, %{"id" => 1712444532121303}}
Link to this function create_message_creative(arg, messages, tx_id \\ nil) 
create_message_creative(page_ref(), [Map.t()], tx_id()) :: res()

Broadcast API / create_message_creatives

Examples 

iex> messages = [%{}]
iex> MessengerBot.create_message_creative({"<AppID>", "<PageID>"}, messages)
{:ok, %{"message_creative_id" => 938461089}}
Link to this function create_messenger_code(arg, req, tx_id \\ nil) 
create_messenger_code(page_ref(), Map.t(), tx_id()) :: res()

Messenger Code API

Examples 

iex> req = %{type: "standard", data: %{ref: "ads"}, image_size: 1000}
iex> MessengerBot.create_messenger_code({"<AppID>", "<PageID>"}, req)
{:ok, %{"uri" => "..."}}
Link to this function delete_custom_label(arg, label_id, tx_id \\ nil) 
delete_custom_label(page_ref(), label_id(), tx_id()) :: res()

Broadcast API / delete_custom_label

Examples 

iex> label_id = 1712444532121303
iex> MessengerBot.delete_custom_label({"<AppID>", "<PageID>"}, label_id)
{:ok, %{"success" => true}}
Link to this function fetch_account_linking_url(arg, tx_id \\ nil) 
fetch_account_linking_url(page_ref(), tx_id()) :: res()

Messenger Profile API / Fetch account linking url

Examples 

iex> MessengerBot.fetch_account_linking_url({"<AppID>", "<PageID>"})
{:ok, %{"data" => [%{"account_linking_url" => "https://..."}]}}
Link to this function fetch_custom_label(arg1, arg2, tx_id \\ nil) 
fetch_custom_label(page_ref(), {label_id(), list()}, tx_id()) :: res()

Broadcast API / fetch_custom_label

Examples 

iex> label_id = 1712444532121303
iex> fields = ~w(name)
iex> MessengerBot.fetch_custom_label({"<AppID>", "<PageID>"}, {label_id, fields})
{:ok, %{"name" => "myLabel", "id" => "1001200005002"}}
Link to this function fetch_get_started(arg, tx_id \\ nil) 
fetch_get_started(page_ref(), tx_id()) :: res()

Messenger Profile API / Fetch get started

Examples 

iex> MessengerBot.fetch_get_started({"<AppID>", "<PageID>"})
{:ok, %{"data" => [%{"get_started" => %{"payload" => "..."}}]}}
Link to this function fetch_greeting(arg, tx_id \\ nil) 
fetch_greeting(page_ref(), tx_id()) :: res()

Messenger Profile API / Fetch greeting

Examples 

iex> MessengerBot.fetch_greeting({"<AppID>", "<PageID>"})
{:ok, %{"data" => [%{"greeting" => [%{}]}]}}
Link to this function fetch_home_url(arg, tx_id \\ nil) 
fetch_home_url(page_ref(), tx_id()) :: res()

Messenger Profile API / Fetch home url

Examples 

iex> MessengerBot.fetch_home_url({"<AppID>", "<PageID>"})
{:ok, %{"data" => [%{"home_url" => %{}}]}}
Link to this function fetch_ids_for_app(arg1, arg2, tx_id \\ nil) 
fetch_ids_for_app(page_ref(), {psid(), cursor()}, tx_id()) :: res()

ID Matching API / ids_for_app

Examples 

iex> psid = 1234567890
iex> cursor = {:after, "NjgyNDk4MTcxOTQzMTY1"}
iex> MessengerBot.fetch_ids_for_app({"<AppID>", nil}, {psid, cursor})
{:ok, %{"data" => [%{"id" => "1429374444444138", }], "paging" => %{}}}
Link to this function fetch_ids_for_page(arg1, arg2, tx_id \\ nil) 
fetch_ids_for_page(page_ref(), {psid(), cursor()}, tx_id()) :: res()

ID Matching API / ids_for_page

Examples 

iex> psid = 1234567890
iex> cursor = nil
iex> MessengerBot.fetch_ids_for_page({"<AppID>", "<PageID>"}, {psid, cursor})
{:ok, %{"data" => [%{"id" => "1429374444444138", }], "paging" => %{}}}
Link to this function fetch_insights(arg1, arg2, tx_id \\ nil) 
fetch_insights(page_ref(), {metrics(), integer(), integer()}, tx_id()) :: res()

Insights API

Examples 

iex> metrics = ~w(page_messages_new_conversations_unique page_messages_active_threads_unique)
iex> MessengerBot.fetch_insights({"<AppID>", "<PageID>"}, {metrics, nil, nil})
{:ok, %{"data" => [%{name: "...", period: "day", values: []}, ]}}
Link to this function fetch_messaging_feature_review(arg, tx_id \\ nil) 
fetch_messaging_feature_review(page_ref(), tx_id()) :: res()

Messaging Feature Review API

Examples 

iex> MessengerBot.fetch_messaging_feature_review({"<AppID>", "<PageID>"})
{:ok, %{"data" => [%{feature: "...", status: "..."}, ]}}
Link to this function fetch_payment_settings(arg, tx_id \\ nil) 
fetch_payment_settings(page_ref(), tx_id()) :: res()

Messenger Profile API / Fetch payment settings

Examples 

iex> MessengerBot.fetch_payment_settings({"<AppID>", "<PageID>"})
{:ok, %{"data" => [%{"payment_settings" => %{}}]}}
Link to this function fetch_persistent_menu(arg, tx_id \\ nil) 
fetch_persistent_menu(page_ref(), tx_id()) :: res()

Messenger Profile API / Fetch persistent menu

Examples 

iex> MessengerBot.fetch_persistent_menu({"<AppID>", "<PageID>"})
{:ok, %{"data" => [%{"persistent_menu" => [%{}, %{}]}]}}
Link to this function fetch_secondary_receivers(arg, fields, tx_id \\ nil) 
fetch_secondary_receivers(page_ref(), fields(), tx_id()) :: res()

Handover Protocol API / secondary_receivers

Link to this function fetch_target_audience(arg, tx_id \\ nil) 
fetch_target_audience(page_ref(), tx_id()) :: res()

Messenger Profile API / Fetch target audience

Examples 

iex> MessengerBot.fetch_target_audience({"<AppID>", "<PageID>"})
{:ok, %{"data" => [%{"target_audience" => %{}}]}}
Link to this function fetch_user_profile(arg1, arg2, tx_id \\ nil) 
fetch_user_profile(page_ref(), {psid(), fields()}, tx_id()) :: res()

User Profile API / user_profiles

Examples 

iex> psid = 1234567890
iex> fields = ~w(first_name last_name profile_pic locale timezone gender)
iex> MessengerBot.fetch_user_profile({"<AppID>", "<PageID>"}, {psid, fields})
{:ok, %{"first_name" => "...", "last_name" => "...", }}
Link to this function fetch_whitelisted_domains(arg, tx_id \\ nil) 
fetch_whitelisted_domains(page_ref(), tx_id()) :: res()

Messenger Profile API / Fetch whitelisted domains

Examples 

iex> MessengerBot.fetch_whitelisted_domains({"<AppID>", "<PageID>"})
{:ok, %{"data" => [%{"whitelisted_domains" => ["https://bit.ly/", ]}]}}
Link to this function label_user(arg1, arg2, tx_id \\ nil) 
label_user(page_ref(), {integer(), Map.t()}, tx_id()) :: res()

Broadcast API / label_user

Examples 

iex> label_id = 1712444532121303
iex> user = %{user: "<PSID>"}
iex> MessengerBot.label_user({"<AppID>", "<PageID>"}, {label_id, user})
{:ok, %{"success" => true}}
Link to this function list_custom_labels(arg1, arg2, tx_id \\ nil) 
list_custom_labels(page_ref(), {fields(), cursor()}, tx_id()) :: res()

Broadcast API / list_custom_labels

Examples 

iex> cursor = {:after, "QVFIUmItNkpTbjVzakxFWGRy"}
iex> fields = ~w(id name)
iex> MessengerBot.list_custom_labels({"<AppID>", "<PageID>"}, {fields, cursor})
{:ok, %{"data" => [], "paging" => {"cursors" => {"after" => "<>", "before" => "<>"}}}}
Link to this function list_custom_labels_of_user(arg1, arg2, tx_id \\ nil) 
list_custom_labels_of_user(page_ref(), {psid(), cursor()}, tx_id()) :: res()

Broadcast API / list_custom_labels_of_user

Examples 

iex> cursor = {:after, "QVFIUmItNkpTbjVzakxFWGRy"}
iex> fields = ~w(id name)
iex> MessengerBot.list_custom_labels_of_user({"<AppID>", "<PageID>"}, {fields, cursor})
{:ok, %{"data" => [], "paging" => {"cursors" => {"after" => "<>", "before" => "<>"}}}}
Link to this function pass_thread_control(arg, req, tx_id \\ nil) 
pass_thread_control(page_ref(), Map.t(), tx_id()) :: res()

Handover Protocol API / pass_thread_control

Link to this function request_thread_control(arg, req, tx_id \\ nil) 
request_thread_control(page_ref(), Map.t(), tx_id()) :: res()

Handover Protocol API / request_thread_control

Link to this function reset_account_linking_url(arg, tx_id \\ nil) 
reset_account_linking_url(page_ref(), tx_id()) :: res()

Messenger Profile API / Reset account linking url

Examples 

iex> MessengerBot.reset_account_linking_url({"<AppID>", "<PageID>"})
{:ok, %{"result" => "success"}}
Link to this function reset_get_started(arg, tx_id \\ nil) 
reset_get_started(page_ref(), tx_id()) :: res()

Messenger Profile API / Reset get started

Examples 

iex> MessengerBot.reset_get_started({"<AppID>", "<PageID>"})
{:ok, %{"result" => "success"}}
Link to this function reset_greeting(arg, tx_id \\ nil) 
reset_greeting(page_ref(), tx_id()) :: res()

Messenger Profile API / Reset greeting

Examples 

iex> MessengerBot.reset_greeting({"<AppID>", "<PageID>"})
{:ok, %{"result" => "success"}}
Link to this function reset_home_url(arg, tx_id \\ nil) 
reset_home_url(page_ref(), tx_id()) :: res()

Messenger Profile API / Reset home url

Examples 

iex> MessengerBot.reset_home_url({"<AppID>", "<PageID>"})
{:ok, %{"result" => "success"}}
Link to this function reset_payment_settings(arg, tx_id \\ nil) 
reset_payment_settings(page_ref(), tx_id()) :: res()

Messenger Profile API / Reset payment settings

Examples 

iex> MessengerBot.reset_payment_settings({"<AppID>", "<PageID>"})
{:ok, %{"result" => "success"}}
Link to this function reset_persistent_menu(arg, tx_id \\ nil) 
reset_persistent_menu(page_ref(), tx_id()) :: res()

Messenger Profile API / Reset persistent menu

Examples 

iex> MessengerBot.reset_persistent_menu({"<AppID>", "<PageID>"})
{:ok, %{"result" => "success"}}
Link to this function reset_target_audience(arg, tx_id \\ nil) 
reset_target_audience(page_ref(), tx_id()) :: res()

Messenger Profile API / Reset target audience

Examples 

iex> MessengerBot.reset_target_audience({"<AppID>", "<PageID>"})
{:ok, %{"result" => "success"}}
Link to this function reset_whitelisted_domains(arg, tx_id \\ nil) 
reset_whitelisted_domains(page_ref(), tx_id()) :: res()

Messenger Profile API / Reset whitelisted domains

Examples 

iex> MessengerBot.reset_whitelisted_domains({"<AppID>", "<PageID>"})
{:ok, %{"result" => "success"}}
Link to this function send_message(arg, req, tx_id \\ nil) 
send_message(page_ref(), Map.t(), tx_id()) :: res()

Send API

Please refer to platform documentation for message types and payloads: https://developers.facebook.com/docs/messenger-platform/reference/send-api/

Examples 

iex> req = %{messaging_type: "...", recipient: %{id: "12"}, message: %{text: "hi!"}}
iex> MessengerBot.send_message({"<AppID>", "<PageID>"}, req)
{:ok, %{recipient_id" => "12", "message_id" => "mid..."}}
Link to this function set_account_linking_url(arg, account_linking_url, tx_id \\ nil) 
set_account_linking_url(page_ref(), String.t(), tx_id()) :: res()

Messenger Profile API / Set account linking url

Examples 

iex> url = "https://example.com/fb/auth"
iex> MessengerBot.set_account_linking_url({"<AppID>", "<PageID>"}, url)
{:ok, %{"result" => "success"}}
Link to this function set_get_started(arg, payload \\ "GET_STARTED", tx_id \\ nil)

Messenger Profile API / Set get started

Examples 

iex> payload = "GET_STARTED"
iex> MessengerBot.set_get_started({"<AppID>", "<PageID>", payload})
{:ok, %{"result" => "success"}}

iex> MessengerBot.set_get_started({"<AppID>", "<PageID>"}, "JUST_STARTED")
{:ok, %{"result" => "success"}}
Link to this function set_greeting(arg, greeting, tx_id \\ nil) 
set_greeting(page_ref(), [Map.t()], tx_id()) :: res()

Messenger Profile API / Set greeting

Examples 

iex> greeting = [%{locale: "default", text: "Hey!"}]
iex> MessengerBot.set_greeting({"<AppID>", "<PageID>"}, greeting)
{:ok, %{"result" => "success"}}
Link to this function set_home_url(arg, home_url, tx_id \\ nil) 
set_home_url(page_ref(), Map.t(), tx_id()) :: res()

Messenger Profile API / Set home url

Examples 

iex> home_url = %{url: "htt..", webview_height_ratio: "tall"}
iex> MessengerBot.set_home_url({"<AppID>", "<PageID>"}, home_url)
{:ok, %{"result" => "success"}}
Link to this function set_payment_settings(arg, payment_settings, tx_id \\ nil) 
set_payment_settings(page_ref(), Map.t(), tx_id()) :: res()

Messenger Profile API / Set payment_settings

Link to this function set_persistent_menu(arg, persistent_menu, tx_id \\ nil) 
set_persistent_menu(page_ref(), list(), tx_id()) :: res()

Messenger Profile API / Set persistent menu

Examples 

iex> menu = []
iex> MessengerBot.set_persistent_menu({"<AppID>", "<PageID>"}, menu)
{:ok, %{"result" => "success"}}
Link to this function set_target_audience(arg, target_audience, tx_id \\ nil) 
set_target_audience(page_ref(), Map.t(), tx_id()) :: res()

Messenger Profile API / Set target audience

Examples 

iex> audience = %{audience_type: "custom", countries: %{whitelist: ["US", "TR"]}}
iex> MessengerBot.set_target_audience({"<AppID>", "<PageID>"}, audience)
{:ok, %{"result" => "success"}}
Link to this function set_whitelisted_domains(arg, whitelisted_domains, tx_id \\ nil) 
set_whitelisted_domains(page_ref(), domains(), tx_id()) :: res()

Messenger Profile API / Set whitelisted domains

Examples 

iex> domains = ["https://bit.ly/", "https://github.com"]
iex> MessengerBot.set_whitelisted_domains({"<AppID>", "<PageID>"}, domains)
{:ok, %{"result" => "success"}}
Link to this function take_thread_control(arg, req, tx_id \\ nil) 
take_thread_control(page_ref(), Map.t(), tx_id()) :: res()

Handover Protocol API / take_thread_control

Link to this function unlabel_user(arg1, arg2, tx_id \\ nil) 
unlabel_user(page_ref(), {integer(), Map.t()}, tx_id()) :: res()

Broadcast API / unlabel_user

Examples 

iex> label_id = 1712444532121303
iex> user = %{user: "<PSID>"}
iex> MessengerBot.unlabel_user({"<AppID>", "<PageID>"}, {label_id, user})
{:ok, %{"success" => true}}
Link to this function upload_attachment(arg, attachment, tx_id \\ nil) 
upload_attachment(page_ref(), Map.t(), tx_id()) :: res()

Attachment Upload API

Examples 

iex> attachment = %{type: "image", payload: %{url: "...", is_reusable: true}}
iex> MessengerBot.upload_attachment({"<AppID>", "<PageID>"}, attachment)
{:ok, %{"attachment_id" => "1857777774821032"}}