conference.go

package gotwilio

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"

	"github.com/google/go-querystring/query"
)

// Conference represents a Twilio Voice conference call
type Conference struct {
	Sid          string `json:"sid"`
	FriendlyName string `json:"friendly_name"`
	Status       string `json:"status"`
	Region       string `json:"region"`
}

// ConferenceOptions are used for updating Conferences
type ConferenceOptions struct {
	Status         string `url:"Status,omitempty"`
	AnnounceURL    string `url:"AnnounceUrl,omitempty"`
	AnnounceMethod string `url:"AnnounceMethod,omitempty"`
}

// ConferenceParticipant represents a Participant in responses from the Twilio API
type ConferenceParticipant struct {
	CallSid                string `json:"call_sid"`
	ConferenceSid          string `json:"conference_sid"`
	Muted                  bool   `json:"muted"`
	Hold                   bool   `json:"hold"`
	Status                 string `json:"status"`
	StartConferenceOnEnter bool   `json:"start_conference_on_enter"`
	EndConferenceOnExit    bool   `json:"end_conference_on_exit"`
	Coaching               bool   `json:"coaching"`
	CallSidToCoach         string `json:"call_sid_to_coach"`
}

// ConferenceParticipantOptions are used for creating and updating Conference Participants.
type ConferenceParticipantOptions struct {
	From                                    string   `url:"From,omitempty"`
	To                                      string   `url:"To,omitempty"`
	StatusCallback                          string   `url:"StatusCallback,omitempty"`
	StatusCallbackMethod                    string   `url:"StatusCallbackMethod,omitempty"`
	StatusCallbackEvent                     []string `url:"StatusCallbackEvent,omitempty"`
	Timeout                                 int      `url:"Timeout"`
	Record                                  *bool    `url:"Record,omitempty"`
	Beep                                    *bool    `url:"Beep,omitempty"`
	Muted                                   *bool    `url:"Muted,omitempty"`
	Hold                                    *bool    `url:"Hold,omitempty"`
	HoldURL                                 *string  `url:"HoldURL,omitempty"`
	HoldMethod                              *string  `url:"HoldMethod,omitempty"`
	AnnounceURL                             *string  `url:"AnnounceURL,omitempty"`
	AnnounceMethod                          *string  `url:"AnnounceMethod,omitempty"`
	StartConferenceOnEnter                  *bool    `url:"StartConferenceOnEnter,omitempty"`
	EndConferenceOnExit                     *bool    `url:"EndConferenceOnExit,omitempty"`
	WaitURL                                 string   `url:"WaitURL,omitempty"`
	WaitMethod                              string   `url:"WaitMethod,omitempty"`
	EarlyMedia                              *bool    `url:"EarlyMedia,omitempty"`
	MaxParticipants                         int      `url:"MaxParticipants"`
	ConferenceRecord                        string   `url:"ConferenceRecord,omitempty"`
	ConferenceTrim                          string   `url:"ConferenceTrim,omitempty"`
	ConferenceStatusCallback                string   `url:"ConferenceStatusCallback,omitempty"`
	ConferenceStatusCallbackMethod          string   `url:"ConferenceStatusCallbackMethod,omitempty"`
	ConferenceStatusCallbackEvent           []string `url:"ConferenceStatusCallbackEvent,omitempty"`
	RecordingChannels                       string   `url:"RecordingChannels,omitempty"`
	RecordingStatusCallback                 string   `url:"RecordingStatusCallback,omitempty"`
	RecordingStatusCallbackMethod           string   `url:"RecordingStatusCallbackMethod,omitempty"`
	RecordingStatusCallbackEvent            string   `url:"RecordingStatusCallbackEvent,omitempty"`
	SipAuthUsername                         string   `url:"SipAuthUsername,omitempty"`
	SipAuthPassword                         string   `url:"SipAuthPassword,omitempty"`
	Region                                  string   `url:"Region,omitempty"`
	ConferenceRecordingStatusCallback       string   `url:"ConferenceRecordingStatusCallback,omitempty"`
	ConferenceRecordingStatusCallbackMethod string   `url:"ConferenceRecordingStatusCallbackMethod,omitempty"`
	Coaching                                *bool    `url:"Coaching,omitempty"`
	CallSidToCoach                          string   `url:"CallSidToCoach,omitempty"`
}

// GetConference fetches details for a single conference instance
// https://www.twilio.com/docs/voice/api/conference-resource#fetch-a-conference-resource
func (twilio *Twilio) GetConference(conferenceSid string) (*Conference, *Exception, error) {
	return twilio.GetConferenceWithContext(context.Background(), conferenceSid)
}

func (twilio *Twilio) GetConferenceWithContext(ctx context.Context, conferenceSid string) (*Conference, *Exception, error) {
	res, err := twilio.get(ctx, twilio.buildUrl(fmt.Sprintf("Conferences/%s.json", conferenceSid)))
	if err != nil {
		return nil, nil, err
	}

	decoder := json.NewDecoder(res.Body)

	// handle NULL response
	if res.StatusCode != http.StatusOK {
		exception := new(Exception)
		err = decoder.Decode(exception)
		return nil, exception, err
	}

	conf := new(Conference)
	err = decoder.Decode(conf)
	return conf, nil, err
}

// UpdateConference to end it or play an announcement
// https://www.twilio.com/docs/voice/api/conference-resource#update-a-conference-resource
func (twilio *Twilio) UpdateConference(conferenceSid string, options *ConferenceOptions) (*Conference, *Exception, error) {
	return twilio.UpdateConferenceWithContext(context.Background(), conferenceSid, options)
}

func (twilio *Twilio) UpdateConferenceWithContext(ctx context.Context, conferenceSid string, options *ConferenceOptions) (*Conference, *Exception, error) {
	form, err := query.Values(options)
	if err != nil {
		return nil, nil, err
	}

	res, err := twilio.post(ctx, form, twilio.buildUrl(fmt.Sprintf("Conferences/%s.json", conferenceSid)))
	if err != nil {
		return nil, nil, err
	}

	decoder := json.NewDecoder(res.Body)

	if res.StatusCode != http.StatusOK {
		exception := new(Exception)
		err = decoder.Decode(exception)
		return nil, exception, err
	}

	c := new(Conference)
	err = decoder.Decode(c)
	return c, nil, err
}

type getParticipantsResponse struct {
	Participants []*ConferenceParticipant `json:"participants"`
}

// GetConferenceParticipants fetches details for all conference participants resource
// https://www.twilio.com/docs/voice/api/conference-participant-resource#read-multiple-participant-resources
func (twilio *Twilio) GetConferenceParticipants(conferenceSid string) ([]*ConferenceParticipant, *Exception, error) {
	return twilio.GetConferenceParticipantsWithContext(context.Background(), conferenceSid)
}

func (twilio *Twilio) GetConferenceParticipantsWithContext(ctx context.Context, conferenceSid string) ([]*ConferenceParticipant, *Exception, error) {
	res, err := twilio.get(ctx, twilio.buildUrl(fmt.Sprintf("Conferences/%s/Participants.json", conferenceSid)))
	if err != nil {
		return nil, nil, err
	}

	decoder := json.NewDecoder(res.Body)

	// handle NULL response
	if res.StatusCode != http.StatusOK {
		exception := new(Exception)
		err = decoder.Decode(exception)
		return nil, exception, err
	}

	conf := new(getParticipantsResponse)
	err = decoder.Decode(conf)

	return conf.Participants, nil, err
}

// GetConferenceParticipant fetches details for a conference participant resource
// https://www.twilio.com/docs/voice/api/conference-participant-resource#fetch-a-participant-resource
func (twilio *Twilio) GetConferenceParticipant(conferenceSid, callSid string) (*ConferenceParticipant, *Exception, error) {
	return twilio.GetConferenceParticipantWithContext(context.Background(), conferenceSid, callSid)
}

func (twilio *Twilio) GetConferenceParticipantWithContext(ctx context.Context, conferenceSid, callSid string) (*ConferenceParticipant, *Exception, error) {
	res, err := twilio.get(ctx, twilio.buildUrl(fmt.Sprintf("Conferences/%s/Participants/%s.json", conferenceSid, callSid)))
	if err != nil {
		return nil, nil, err
	}

	decoder := json.NewDecoder(res.Body)

	// handle NULL response
	if res.StatusCode != http.StatusOK {
		exception := new(Exception)
		err = decoder.Decode(exception)
		return nil, exception, err
	}

	conf := new(ConferenceParticipant)
	err = decoder.Decode(conf)
	return conf, nil, err
}

// AddConferenceParticipant adds a Participant to a conference by dialing out a new call
// https://www.twilio.com/docs/voice/api/conference-participant-resource#create-a-participant-agent-conference-only
func (twilio *Twilio) AddConferenceParticipant(conferenceSid string, participant *ConferenceParticipantOptions) (*ConferenceParticipant, *Exception, error) {
	return twilio.AddConferenceParticipantWithContext(context.Background(), conferenceSid, participant)
}

func (twilio *Twilio) AddConferenceParticipantWithContext(ctx context.Context, conferenceSid string, participant *ConferenceParticipantOptions) (*ConferenceParticipant, *Exception, error) {
	form, err := query.Values(participant)
	if err != nil {
		return nil, nil, err
	}

	res, err := twilio.post(ctx, form, twilio.buildUrl(fmt.Sprintf("Conferences/%s/Participants.json", conferenceSid)))
	if err != nil {
		return nil, nil, err
	}

	decoder := json.NewDecoder(res.Body)

	if res.StatusCode != http.StatusCreated {
		exception := new(Exception)
		err = decoder.Decode(exception)
		return nil, exception, err
	}

	conf := new(ConferenceParticipant)
	err = decoder.Decode(conf)
	return conf, nil, err
}

// UpdateConferenceParticipant
// https://www.twilio.com/docs/voice/api/conference-participant-resource#create-a-participant-agent-conference-only
func (twilio *Twilio) UpdateConferenceParticipant(conferenceSid string, callSid string, participant *ConferenceParticipantOptions) (*ConferenceParticipant, *Exception, error) {
	return twilio.UpdateConferenceParticipantWithContext(context.Background(), conferenceSid, callSid, participant)
}

func (twilio *Twilio) UpdateConferenceParticipantWithContext(ctx context.Context, conferenceSid string, callSid string, participant *ConferenceParticipantOptions) (*ConferenceParticipant, *Exception, error) {
	form, err := query.Values(participant)
	if err != nil {
		return nil, nil, err
	}

	res, err := twilio.post(ctx, form, twilio.buildUrl(fmt.Sprintf("Conferences/%s/Participants/%s.json", conferenceSid, callSid)))
	if err != nil {
		return nil, nil, err
	}

	decoder := json.NewDecoder(res.Body)

	if res.StatusCode != http.StatusOK {
		exception := new(Exception)
		err = decoder.Decode(exception)
		return nil, exception, err
	}

	p := new(ConferenceParticipant)
	err = decoder.Decode(p)
	return p, nil, err
}

// DeleteConferenceParticipant
func (twilio *Twilio) DeleteConferenceParticipant(conferenceSid string, callSid string) (*Exception, error) {
	return twilio.DeleteConferenceParticipantWithContext(context.Background(), conferenceSid, callSid)
}

func (twilio *Twilio) DeleteConferenceParticipantWithContext(ctx context.Context, conferenceSid string, callSid string) (*Exception, error) {
	res, err := twilio.delete(ctx, twilio.buildUrl(fmt.Sprintf("Conferences/%s/Participants/%s.json", conferenceSid, callSid)))
	if err != nil {
		return nil, err
	}

	if res.StatusCode != http.StatusOK {
		decoder := json.NewDecoder(res.Body)
		exception := new(Exception)
		err = decoder.Decode(exception)
		return exception, err
	}

	return nil, err
}